The FiPy finite volume PDE solver relies on severalthird-party packages. It is best to obtain and install those firstbefore attempting to install FiPy. This document explains howto install FiPy, not how to use it. See Using FiPyfor details on how to use FiPy.
Note
It may be useful to set up a Development Environment before beginningthe installation process.
Note
By selecting the links on this page, you will be leaving NISTwebspace. We have provided these links to other web sites becausethey may have information that would be of interest to you. Noinferences should be drawn on account of other sites beingreferenced, or not, from this page. There may be other web sites thatare more appropriate for your purpose. NIST does not necessarilyendorse the views expressed, or concur with the facts presented onthese sites. Further, NIST does not endorse any commercial productsthat may be mentioned on these sites. Please address comments aboutthis page to fipy@list.nist.gov.
Pre-Installed on Binder¶
A full FiPy installation is available for basic exploration onBinder. The default notebook gives a rudimentary introduction to FiPysyntax and, like any Jupyter Notebook interface, tab completion will helpyou explore the package interactively.
Recommended Method¶
Attention
There are many ways to obtain the softwarepackages necessary to run FiPy, but the most expedient way iswith the conda package manager. In addition to the scientificPython stack, conda also provides virtual environmentmanagement. Keeping separate installations is useful e.g. forcomparing Python 2 and Python 3 software stacks, or whenthe user does not have sufficient privileges to install softwaresystem-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 provideseverything 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 condaenvironment and then download and populate the environment with theprerequisites for FiPy from the conda-forge channel athttps://anaconda.org. See this discussionof the merits of and relationship between the different methods.
Conda environment files
This option is the most upgradable in the future and probably the bestfor development.
$ conda env create --name <MYFIPYENV> \ --file environments/<SOLVER>-environment.yml
Note
You can try to include multiple solver suites using
conda envupdate, but be aware that different suites may have incompatiblerequirements, or may restrict installation to obsolete versions ofPython. Given that FiPy can only use one solver suite duringa run, installing more than one solver in an environment isn’tnecessary.Attention
Successively updating an environment can be unpredictable, as laterpackages may conflict with earlier ones. Unfortunately,
condaenv createdoes not support multiple environment files.Alternatively, combine the different
environments/<SOLVER>-environment.ymlfiles you wish touse, along with environment.yml files for any other packages youare 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, butnot particularly upgradable. For most, this is the safest way togenerate 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 orincompatible 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 thatVTKViewers can raise errors(probably other uses of Mayavi, too). Hence, the constraintof “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”, butwe found this to be too fragile. It now only includes the bareminimum 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 bequiteslowto resolve all dependencies when performingan installation. You may wish to consider using the alternativemamba installation manager to speed things up.
Note
On Linux and Mac OS X, you should have a pretty complete systemto run and visualize FiPy simulations. On Windows, thereare fewer packages available via conda, particularly amongst thesparse matrix Solvers, but the system still should befunctional. Significantly, you will need to download and installGmsh manually when using Python 2.7.
Attention
When installed via conda or pip, FiPy will not includeits examples. These can be obtained bycloning the repository or downloading a compressed archive.
Obtaining FiPy¶
FiPy is freely available for download via Git or as acompressed archive. Please seeGit usage for instructions on obtaining FiPywith Git.
Warning
Keep in mind that if you choose to download the compressedarchive you will then need to preserve your changes when upgradesto FiPy become available (upgrades via Git will handlethis issue automatically).
Installing FiPy¶
Details of the Required Packages and links are given below,but for the courageous and theimpatient, FiPy can be up and running quickly by simplyinstalling 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 runwithout a viewer, but you’ll want one for any practical work)
Other Optional Packages add greatly to FiPy’scapabilities, but are not necessary for an initial installation or tosimply run the test suite.
It is not necessary to formally install FiPy, but if you wishto do so and you are confident that all of the requisite packages havebeen 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 installFiPy in “development mode” by typing:
$ python setup.py develop
which allows the source code to be altered in place and executed withoutissuing further installation commands.
Alternatively, you may choose not to formally install FiPy andto simply work within the base directory instead. In this case or if youare making a non-standard install (without admin privileges), read aboutsetting up your Development Environment before beginning the installationprocess.
Required Packages¶
Python¶
FiPy is written in the Python language and requires aPython installation to run. Python comes pre-installedon many operating systems, which you can check by opening a terminaland typing python, e.g.:
$ pythonPython 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 optionalpackages is available with one of the following distributions.
NumPy¶
Obtain and install the NumPy package. FiPy requires atleast version 1.0 of NumPy.
Optional Packages¶
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¶
SciPy provides a large collection of functions and tools that canbe useful for running and analyzing FiPy simulations. Significantlyimproved performance has been achieved with the judicious use of C languageinlining (see the Command-line Flags and Environment Variables section for moredetails), via the weave module.
Level Set Packages¶
To use the level set ([8]) components of FiPy one of the following isrequired.
Scikit-fmm¶
http://packages.python.org/scikit-fmm/
Scikit-fmm is a python extension module which implements the fastmarching method.
LSMLIB¶
http://ktchu.serendipityresearch.org/software/lsmlib/index.html
The Level Set Method Library (LSMLIB) provides support for the serialand parallel simulation of implicit surface and curve dynamics in two-and three-dimensions.
Install LSMLIB as per the instructions on the website. AdditionallyPyLSMLIB is required. To install, follow the instructions on thewebsite,https://github.com/ktchu/LSMLIB/tree/master/pylsmlib#pylsmlib.
Development Environment¶
It is often preferable to not formally install packages in the systemdirectories. The reasons for this include:
developing or altering the package source code,
trying out a new package along with its dependencies withoutviolating 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 oneof the utilities that manage packages and their dependencies independentlyof the system package manager and the system directories. These utilitiesinclude 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 Gitrepository at GitHub. You can browse through the code athttps://github.com/usnistgov/fipy and, using a Git client, you candownload various tagged revisions of FiPy depending on your needs.
Attention
Be sure to follow Installation to obtain all the prerequisites forFiPy.
Git client¶
A git client application is needed in order to fetch files from ourrepository. This is provided on many operating systems (try executingwhich git) but needs to be installed on many others. The sources tobuild Git, as well as links to various pre-built binaries fordifferent platforms, can be obtained from http://git-scm.com/.
Git branches¶
In general, most users will not want to download the very latest state ofFiPy, as these files are subject to active development and may not behaveas desired. Most users will not be interested in particular version numberseither, but instead with the degree of code stability. Different branches areused to indicate different stages of FiPy development. For themost part, we follow a successful Git branching model. You willneed to decide on your own risk tolerance when deciding which stage ofdevelopment 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> ofdevelopment by issuing the command:
$ git checkout <branch>
in the base directory of the working copy. The main branches for FiPy are:
masterdesignates the (ready to) release state of FiPy. This code is stableand should pass all of the tests (or should be documented that it doesnot).
Past releases of FiPy are tagged as
x.y.zAny released version of FiPy will be designated with a fixed tag: Thecurrent version of FiPy is 3.4.5. (Legacy
version-x_y_ztagsare 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 onbranches, only merged back to master when the tests passsuccessfully. Although we cannot guarantee that master will neverbe broken, you can always check our Continuous Integration statusto find the most recent revision that it is running acceptably.
Historically, we merged to develop before merging to master. Weno longer do this, although for time being, develop is keptsynchronized with master. In a future release, we will remove thedevelop branch altogether.
For those who are interested in learning more about Git, a wide variety ofonline 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 FiPyusing Nix. Nix is a powerful package manager for Linux and otherUnix systems that makes package management reliable andreproducible. The recipe works on both Linux and Mac OS X. Go tonix.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 Python3 by default. nix develop drops the user into a shell with a workingversion 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.
