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

This describes the steps required to get GlobSim up and running.  You can either install all the packages and dependencies yourself, or you can learn about :ref:`docker`. 

GlobSim
-------

GlobSim is most easily used by creating a conda environment::

    git clone https://github.com/geocryology/globsim
    cd globsim
    conda env create -f globsim.py36.yml
    conda activate globsim
    python setup.py install

Required libraries
------------------

NetCDF
^^^^^^
NetCDF files are used to store data in a standard format. The NCO libraries must be installed and built on your computer for GlobSim to work.  Instructions can be found on the `Unidata website <https://www.unidata.ucar.edu/software/netcdf/docs/getting_and_building_netcdf.html>`_. 

ECMWF Client libraries
^^^^^^^^^^^^^^^^^^^^^^
ECMWF is used to access ERA files. Python libraries (supporting python 2.7 and 3) to access the API are available from the `ECMWF website <https://confluence.ecmwf.int/display/WEBAPI/Accessing+ECMWF+data+servers+in+batch>`_

Grib API and pygrib
^^^^^^^^^^^^^^^^^^^
GlobSim uses the `GRIB API <https://confluence.ecmwf.int/display/GRIB/What+is+GRIB-API>`_. 
Python bindings to the GRIB API are also necessary `(pygrib) <https://jswhit.github.io/pygrib/docs/>`_. The code was tested using pygrib version 2.0.1. 

ESMF and ESMPy
^^^^^^^^^^^^^^
GLOBSIM uses ESMF libraries to do efficient regridding. These libraries must be built on your machine and have additional dependencies.  ESMP version 7.1.0r is supported. To download ESMF, consult the `ESMF Users Guide <http://www.earthsystemmodeling.org/esmf_releases/public/ESMF_7_1_0r/ESMF_usrdoc/>`_, particularly sections 5 and 8.

ESMPy provides python bindings for the ESMF libraries.  If you have successfully installed the ESMF libraries, you can follow the instructions `here <http://www.earthsystemmodeling.org/esmf_releases/public/ESMF_7_1_0r/esmpy_doc/html/install.html#installing-esmpy>`_ to extract the python bindings.  More info is available at the `ESMPy main page <https://www.earthsystemcog.org/projects/esmpy/>`_.

The following example script was used to install on Ubuntu 16.04::


    # GRIB API
    apt install libgrib-api-dev

    #python libraries
    apt install python3-pip
    pip3 install numpy
    pip3 install nco
    pip3 install netCDF4
    pip3 install scipy
    pip3 install pandas
    pip3 install pydap
    pip3 install python-dateutil
    pip3 install pyproj
    pip3 install pygrib==2.0.1  # requires grib API
    pip3 install lxml

    # ECMWFAPI
    pip3 install https://software.ecmwf.int/wiki/download/attachments/56664858/ecmwf-api-client-python.tgz 

    ## Netcdf - C
    apt install netcdf-bin
    apt install libnetcdf-dev

    ## Netcdf - Fortran
    apt install libnetcdff-dev

    ## fortran compiler
    apt install gfortran

    ## open mpi
    apt install libopenmpi-dev

    # ESMF
    wget \"http://www.earthsystemmodeling.org/esmf_releases/public/ESMF_7_1_0r/esmf_7_1_0r_src.tar.gz\"

To install ESMF, the following script was then used (again, tested on Ubuntu 16.04)::
   
    #!/bin/bash

    set -e

    export BASE_DIR=$(pwd)

    export ESMF_DIR=${BASE_DIR}/esmf
    export ESMF_INSTALL_PREFIX=${BASE_DIR}/esmf-install
    export ESMF_NETCDF=split
    export ESMF_NETCDF_LIBPATH=/usr/lib/x86_64-linux-gnu/
    export ESMF_NETCDF_LIBS="-lnetcdff -lnetcdf"
    export ESMF_NETCDF_INCLUDE=/usr/include

    export ESMF_COMPILER=gfortran
    export ESMF_COMM=openmpi


    tar xvf ~/esmf_7_1_0r_src.tar

    cd esmf
    make -j 12
    # make check # (optional)

    make install
    # make installcheck # (optional)

    cd src/addon/ESMPy
   
    python setup.py  build --ESMFMKFILE=${ESMF_DIR}/lib/libO/Linux.gfortran.64.openmpi.default/esmf.mk install


    echo "To use this version of ESMPy, run:"
    echo "  export PYTHONPATH='$BASE_DIR/python/lib/python2.7/site-packages'"