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

PyCIF is a Python package that can be installed with `pip <https://pip.pypa.io/en/stable/>`__.
While :bash:`pip` will install all the *Python* dependencies automatically, PyCIF also
rely on some external libraries and tools, that need to be installed first.

Dependencies
------------

PyCIF depends on some external libraries and tools that need to be installed
on your system, or loaded in the environment with the :bash:`module` command
on computing clusters.

.. tip::

    A Docker image with all requirements pre-installed is available on
    `Docker Hub <https://hub.docker.com/r/pycif/pycif-ubuntu>`__.
    See :doc:`CIF in Docker documentation </docker/index>` for details on the CIF docker image.

Here is a list of PyCIF dependencies:

- `Python <https://www.python.org/>`__ (version 3.9 or above)
- rsync
- `git <https://git-scm.com/>`__
- `ecCodes <https://confluence.ecmwf.int/display/ECC//>`__
- `GDAL <https://gdal.org/>`__
- `PROJ <https://proj.org/>`__
- `HDF5 <https://www.hdfgroup.org/solutions/hdf5/>`__
- `netCDF4 <https://www.unidata.ucar.edu/software/netcdf/>`__

.. - `graphviz <https://graphviz.org/>`__

.. note::

    Models included in CIF have also their own dependencies (compiler,
    parallel computing librairies, NetCDF librairy).
    Please refer to the `Dockerfile <https://gitlab.in2p3.fr/satinv/cif/-/blob/main/Dockerfile>`__ for a full list of
    required packages on Ubuntu based systems.


Installing PyCIF
----------------

Once all the dependencies are installed, you can install PyCIF with one of the
following method:

From a release
~~~~~~~~~~~~~~

.. hint::

    Use this installation method if you do not need to modify PyCIF's code.

Download PyCIF wheel form the `latest release <https://gitlab.in2p3.fr/satinv/cif/-/releases/permalink/latest/downloads/pycif-py3-none-any.whl>`__
or choose another release from the `release page <https://gitlab.in2p3.fr/satinv/cif/-/releases>`__.

Install the downloaded wheel file with :bash:`pip`:

.. code-block:: shell

    pip install --user pycif-*-py3-none-any.whl

From sources
~~~~~~~~~~~~

.. hint::

    Use this installation method if you need to modify PyCIF's code or need to use
    some functionalities that are not yet in the latest release.

Clone the `CIF repository <https://gitlab.in2p3.fr/satinv/cif>`__,
choose the desired branch/commit and install PyCIF with :bash:`pip`
(preferably in editable mode):

.. code-block:: shell

    git clone git@gitlab.in2p3.fr:satinv/cif.git
    cd cif
    git checkout devel # Switch to the development branch, optional
    pip install --user --editable .


.. tip::

    If PyCIF is installed in editable mode, you can update PyCIF at anytime with :bash:`git pull`

Possible issue with GDAL
------------------------

The GDAL Python package is sometimes not installed with numpy-based raster support.
You can verify that numpy-based raster support has been installed with the command:

.. code-block:: shell

    python -c 'from osgeo import gdal_array'


If not, you can re-install the GDAL Python package properly with:

.. code-block:: shell

    pip install numpy wheel setuptools>=67
    pip install --no-build-isolation --no-cache-dir --force-reinstall gdal==$(gdal-config --version).*

Compiling models
----------------

To compile the models included in CIF, please refer to the
:doc:`models documentation </documentation/doc-models/index>`.