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 USAGE
for details on how to use FiPy
.
Note
It may be useful to set up a ENVIRONMENT
before beginning the installation process.
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 fipy@list.nist.gov.
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.
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.
$ 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 USAGE
.
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 <part:examples>
. These can be obtained by cloning the repository or downloading a compressed archive.
FiPy
is freely available for download via Git or as a compressed archive. Please see documentation:GIT
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).
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:
Other OPTIONALPACKAGES
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 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 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.
Obtain and install the NumPy
package. FiPy
requires at least version 1.0 of NumPy.
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
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 FlagsAndEnvironmentVariables
section for more details), via the weave
module.
To use the level set (levelSetBook
) components of 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.
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_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