.. title:: Installation


============
Installation
============

FFC is normally installed as part of an installation of FEniCS.
If you are using FFC as part of the FEniCS software suite, it
is recommended that you follow the
`installation instructions for FEniCS
<https://fenics.readthedocs.io/en/latest/>`__.

To install FFC itself, read on below for a list of requirements
and installation instructions.

Requirements and dependencies
=============================

FFC requires Python version 2.7 or later and depends on the
following Python packages:

* NumPy
* six

FFC also depends on the following FEniCS Python packages:

* FIAT
* UFL
* dijitso

These packages will be automatically installed as part of the
installation of FFC, if not already present on your system.

.. _tsfc_requirements:

TSFC requirements
-----------------

To use experimental ``tsfc`` representation, additional
dependencies are needed:

* `TSFC <https://github.com/blechta/tsfc>`_ [1]_
* `COFFEE <https://github.com/blechta/COFFEE>`_ [1]_
* `FInAT <https://github.com/blechta/FInAT>`_ [1]_

and in turn their additional dependencies:

* singledispatch [2]_
* networkx [2]_
* PuLP [2]_, [4]_
* GLPK [3]_, [4]_

.. note:: TSFC requirements are not installed in FEniCS Docker
    images by default yet but they can be easilly installed
    on demand::

        docker pull quay.io/fenicsproject/stable:2017.1.0
        docker run -ti --rm quay.io/fenicsproject/stable:2017.1.0
        sudo apt-get update && sudo apt-get -y install glpk-utils && \
          sudo pip2 install --prefix=${FENICS_PREFIX} --no-cache-dir \
          git+https://github.com/blechta/tsfc.git@2017.1.0 \
          git+https://github.com/blechta/COFFEE.git@2017.1.0 \
          git+https://github.com/blechta/FInAT.git@2017.1.0 \
          singledispatch networkx pulp && \
          sudo pip3 install --prefix=${FENICS_PREFIX} --no-cache-dir \
          git+https://github.com/blechta/tsfc.git@2017.1.0 \
          git+https://github.com/blechta/COFFEE.git@2017.1.0 \
          git+https://github.com/blechta/FInAT.git@2017.1.0 \
          singledispatch networkx pulp && \
          sudo apt-get clean && \
          sudo rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*

    The first two commands (or their modification, or
    ``fenicsproject`` helper script) are to be run on a host,
    while the last command, to be run in the container, actually
    installs all the TSFC requirements. For further reading,
    see `FEniCS Docker reference
    <https://fenics-containers.readthedocs.io/>`_.

.. [1] These are forks of the original packages tested to be
   compatible with FFC and updated frequently from upstream.

.. [2] Pip-installable.

.. [3] Binary package; ``glpsol`` executable needed. Version
    ``GLPSOL: GLPK LP/MIP Solver, v4.57`` from Ubuntu 16.04
    ``glpk-utils`` package is known to produce the same
    references as our test system.

.. [4] Needed for certain COFFEE optimizations.

Installation instructions
=========================

To install FFC, download the source code from the
`FFC Bitbucket repository
<https://bitbucket.org/fenics-project/ffc>`__,
and run the following command:

.. code-block:: console

    pip install .

To install to a specific location, add the ``--prefix`` flag
to the installation command:

.. code-block:: console

    pip install --prefix=<some directory> .
