.. currentmodule:: cf
.. default-role:: obj

.. _Installation:

**Installation**
================

----

Version |release| for version |version| of the CF conventions.

.. contents::
   :local:
   :backlinks: entry

.. _Operating-systems:

**Operating systems**
---------------------

cf works only for Linux and Mac operating systems.

If you have a Windows operating system then you can either install the
`Microsoft Windows Subsystem for Linux (WSL)
<https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux>`_, or
installing a Linux Virtual Machine also works.

----

.. _Python-versions:

**Python versions**
-------------------

cf at versions 3.0.0 or later works only for Python 3.5 or
later. (Versions 2.x of cf work only for Python 2.7.)

----

.. _conda:
  
**conda**
---------

cf-python is in the ``ncas`` conda channel. To install cf with all of
its :ref:`required <Required>` and :ref:`optional <Optional>`
dependencies, and the `cf-plot visualisation package
<http://ajheaps.github.io/cf-plot>`_, run

.. code-block:: shell
   :caption: *Install with conda.*
	     
   conda install -c ncas -c conda-forge cf-python cf-plot udunits2==2.2.25
   conda install -c conda-forge mpich esmpy

The second of the two ``conda`` commands is required for
:ref:`regridding <Regridding>` to work. (Note, however, that the
installation of ``esmpy`` does not work for Anaconda version
``2019.10``.)

Note that :ref:`some environment variables might also need setting
<UNIDATA-UDUNITS-2-library>` in order for the UDUNITS library to work
properly, although the defaults are usually sufficient.

----

.. _pip:
  
**pip**
-------

cf-python is in the Python package index:
https://pypi.org/project/cf-python
  
To install cf and all of its :ref:`required dependencies <Required>`
run, for example:

.. code-block:: shell
   :caption: *Install as root, with any missing dependencies.*
	     
   pip install cf-python

.. code-block:: shell
   :caption: *Install as a user, with any missing dependencies.*
	     
   pip install cf-python --user

To install cf without any of its dependencies then run, for example:

.. code-block:: shell
   :caption: *Install as root without installing any of the
             dependencies.*
	     
   pip install cf-python --no-deps

See the `documentation for pip install
<https://pip.pypa.io/en/stable/reference/pip_install/>`_ for further
options.

The :ref:`optional dependencies <Optional>` are **not** automatically
installed via ``pip``.


Note that :ref:`some environment variables might also need setting
<UNIDATA-UDUNITS-2-library>` in order for the UDUNITS library to work
properly, although the defaults are usually sufficient.

----

.. _Source:

**Source**
----------

To install from source:

1. Download the cf-python package from https://pypi.org/project/cf-python

2. Unpack the library (replacing ``<version>`` with the version that
   you want to install, e.g. ``3.0.0``):

   .. code:: bash
	 
      tar zxvf cf-python-<version>.tar.gz
      cd cf-python-<version>

3. Install the package:
  
  * To install the cf-python package to a central location:

    .. code:: bash
	 
       python setup.py install

  * To install the cf-python package locally to the user in the default
    location:

    .. code:: bash

       python setup.py install --user

  * To install the cf-python package in the <directory> of your choice:

    .. code:: bash

       python setup.py install --home=<directory>

Note that :ref:`some environment variables might also need setting
<UNIDATA-UDUNITS-2-library>` in order for the UDUNITS library to work
properly, although the defaults are usually sufficient.

----

.. _cfa-utility:

**cfa utility**
---------------

During installation the ``cfa`` command line utility is also
installed, which

* :ref:`generates text descriptions of field constructs contained in
  files <File-inspection-with-cfa>`, and 

* :ref:`creates new datasets aggregated from existing files
  <Creation-with-cfa>`.

----

.. _Dependencies:

**Dependencies**
----------------

.. _Required:

Required
^^^^^^^^

* `Python <https://www.python.org/>`_, version 3.5 or newer.

* `numpy <https://pypi.org/project/numpy/>`_, version 1.15 or newer.

* `netCDF4 <https://pypi.org/project/netcdf4/>`_, version 1.4.0 or
  newer.

* `cftime <https://pypi.org/project/cftime/>`_, version 1.0.4.2 or
  newer. (Note that this package is installed with netCDF4.)

* `cfdm <https://pypi.org/project/cfdm/>`_, version 1.7.9 or newer.
  
* `cfunits <https://pypi.org/project/cfunits/>`_, version 3.2.2 or newer.
  
* `psutil <https://pypi.org/project/psutil/>`_, version 0.6.0 or newer.

.. _UNIDATA-UDUNITS-2-library:

* `UNIDATA UDUNITS-2 library
  <http://www.unidata.ucar.edu/software/udunits>`_, version 2.2.20 or
  newer.

  This is a C library which provides support for units of physical
  quantities. If the UDUNITS-2 shared library file
  (``libudunits2.so.0`` on GNU/Linux or ``libudunits2.0.dylibfile`` on
  MacOS) is in a non-standard location then its directory path should
  be added to the ``LD_LIBRARY_PATH`` environment variable. It may
  also be necessary to specify the location (directory path *and*
  file name) of the ``udunits2.xml`` file in the ``UDUNITS2_XML_PATH``
  environment variable (although the default location is usually
  correct). For example, ``export
  UDUNITS2_XML_PATH=/home/user/anaconda3/share/udunits/udunits2.xml``.
  If you get an error that looks like ``assert(0 ==
  _ut_unmap_symbol_to_unit(_ut_system, _c_char_p(b'Sv'), _UT_ASCII))``
  then setting the ``UDUNITS2_XML_PATH`` environment variable is the
  likely solution.
  
.. _Optional:

Optional
^^^^^^^^

Some further dependencies that enable further functionality are
optional. This to facilitate cf-python being installed in restricted
environments in which these features are not required.

.. rubric:: Regridding

* `ESMF <https://www.earthsystemcog.org/projects/esmpy/>`_, version
  7.1.0r or newer. This is easily installed via conda with

  .. code:: bash

     conda install -c conda-forge mpich esmpy

  or may be installed from source.

.. rubric:: Convolution filters, derivatives and relative vorticity

* `scipy <https://pypi.org/project/scipy>`_, version 1.1.0 or newer.

.. rubric:: Subspacing based on N-dimensional construct cells (N > 1)
            containing a given value

* `matplotlib <https://pypi.org/project/matplotlib>`_, version 3.0.0
  or newer.

.. rubric:: Parallel processing

* `mpi4py <https://pypi.org/project/mpi4py>`_

----

.. _Tests:

**Tests**
---------

Tests are run from within the ``cf/test`` directory:

.. code:: bash
 
   python run_tests.py
       
----

.. _Code-repository:

**Code repository**
-------------------

The complete source code and issue tracker is available at
https://github.com/NCAS-CMS/cf-python

.. .. rubric:: Footnotes

   .. [#installfiles] The ``requirements.txt`` file contains

     .. include:: ../../requirements.txt
        :literal: