Installation

Version 3.9.0 for version 1.8 of the CF conventions.

Note

The latest versions of cf available from the Python package index (PyPI) and conda are confirmed at the top of the README document.

Operating systems

The cf package 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), or installing a Linux Virtual Machine also works.

Python versions

The cf package is only Python 3.6 or later.

Note

Python 3.6 support is deprecated and will be removed at the next release.

Versions 2.x of cf work only for Python 2.7.

pip

cf is in the Python package index: https://pypi.org/project/cf-python

To install cf and all of its required dependencies (there are also has some optional dependencies which are not automatically installed via pip) run, for example:

Install as root, with any missing dependencies.
$ pip install cf-python
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:

Install as root without installing any of the dependencies.
$ pip install cf-python --no-deps

See the documentation for pip install for further options.

Note that some environment variables might also need setting in order for the UDUNITS library to work properly, although the defaults are usually sufficient.

conda

The cf package is in the ncas conda channel. To install cf with all of its required and optional dependencies, and the cf-plot visualisation package, run

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 regridding to work. (Note, however, that the installation of esmpy does not work for Anaconda version 2019.10.)

Note that some environment variables might also need setting in order for the UDUNITS library to work properly, although the defaults are usually sufficient.

Source

To install from source:

  1. Download the cf 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.9.0):

    $ 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:

    $ python setup.py install

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

    $ python setup.py install --user

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

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

Note that some environment variables might also need setting in order for the UDUNITS library to work properly, although the defaults are usually sufficient.

cfa utility

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

Dependencies

Required

  • Python, 3.6 or newer, including the latest version Python 3.9.

  • numpy, 1.15 or newer.

  • netCDF4, 1.5.4 or newer.

  • cftime, version 1.5.0 or newer (note that this package may be installed with netCDF4).

  • cfdm, version 1.8.9.0 or up to, but not including, 1.8.10.0.

  • cfunits, version 3.3.3 or newer.

  • psutil, version 0.6.0 or newer.

  • UNIDATA UDUNITS-2 library, 2.2.20 <= version. UDUNITS-2 is a C library that 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 a run-time 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

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

Regridding

  • ESMF, version 8.0.0 or newer. This is easily installed via conda with

    $ conda install -c conda-forge mpich esmpy

    or may be installed from source.

Convolution filters, derivatives and relative vorticity

  • scipy, version 1.1.0 or newer.

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

Parallel processing

Tests

Tests are run from within the cf/test directory:

$ python run_tests.py

Code repository

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