Installing ISCE on Centos 7.5 / Ubuntu 18.04

Table of Contents

• Installing packages using builtin package manager
  • yum on Centos 7.5
    • gcc7 on Centos7.5
  • apt-get on Ubuntu 18.04
• Installing Anaconda and Python packages
• Install ISCE from source
  • Step 1: Get latest version of ISCE source
    • Option 1: Checkout latest version from git
    • Option 2: Get the latest tarball
  • Step 2: Build the software
  • Step 3: Install and set environment variables

ISCE has the following dependencies

1. C++ compiler - gcc-6 or above
2. Python 3.6 or above
3. Numpy and Cython
4. GDAL 2.3 or above with Python bindings
5. HDF5 1.10.2 or above with h5py
6. cmake 3.12 or above
7. CUDA 9.0 or above (for GPU-based processing)
8. ruamel.yaml

Optional dependencies for unit testing and documentation generation are

1. pytest (for Python unit tests)
2. sphinx (for documenting Python code)
3. doxygen (for documenting C++ code)

As of Jan 2020, Centos 7.5 is the operational OS for the NISAR processing system and this is
probably the most tested set of instructions. The instructions for Centos 7.5 / Ubuntu 18.04
are more or less the same except for the parts specific to using the standard package managers
to install compilers and some basic packages.

We will install all dependencies under a folder called ${ISCEHOME} in the instructions below.
Our overall strategy for directory layouts is as follows:

Assumed directory structure for installation

Path	Description
${ISCEHOME}/python/miniconda3	Miniconda3 installation directory
${ISCEHOME}/tools/isce/src	git checkout location/ unpacked tarball location of ISCE source
${ISCEHOME}/tools/isce/build	cmake build location
${ISCEHOME}/tools/isce/install	cmake install location
${ISCEHOME}/tools/gcc7	Directory for gcc7 compiled from source (Only for Centos 7.5)

Note that ${ISCEHOME} in these can be any directory on your machine. You can even use your home
folder as the base for your directory structure.

Installing packages using builtin package manager

yum on Centos 7.5

This section only applies to installation on Centos 7.5. The following packages and their dependencies
should be installed using "yum".

1. curl
2. sudo
3. bzip2
4. zip

If CUDA support is desired, install the following set of packages with yum as well:

1. cuda-libraries-dev-10.1
2. cuda-nvml-dev-10.1
3. cuda-minimal-build-10.1
4. cuda-command-line-tools-10.1

gcc7 on Centos7.5

Centos 7.5 is a fairly old distribution and attempts to guarantee backward compatibility. As a result, the gcc/g++ compilers that are included with this distribution do not support
gcc's dual ABI. Hence, you will have to build a gcc compiler ( version > 6) manually for use.

1. If you are within JPL, you can get a version of gcc7 here: https://github-fn.jpl.nasa.gov/NISAR-ADT/gcc7/releases/download/v0.0.1/gcc7.tar.gz .

2. Untar the contents of this file to ${ISCEHOME}/tools/gcc7

   tar xzv gcc7.tar.gz -C ${ISCEHOME}/tools
   

apt-get on Ubuntu 18.04

This section only applies to installation on Ubuntu 18.04. The following packages and their
dependencies should be installed using "apt-get".

1. gnupg2
2. curl
3. ca-certificates
4. bzip2
5. zip
6. gcc-6
7. g++-6

If CUDA support is desired, install the following set of packages with apt-get as well:

1. nvidia-cuda-toolkit

Installing Anaconda and Python packages

In this set of instructions, we rely on Anaconda for installing
Python dependencies. We will install Python3 to the location ${ISCEHOME}/python/miniconda3.

1. We will list all the required packages in a text file called "requirements.txt" located under ${ISCEHOME}/python.
   The contents of the requirements.txt file is shown below:

   cmake
   cython
   gdal
   git
   h5py
   libgdal
   pytest
   numpy
   fftw
   scipy
   pyproj
   matplotlib
   pandas
   sphinx
   ruamel.yaml

2. We can then install Anaconda and these requirements as shown below:

   > cd ${ISCEHOME}/python
   > curl -sSL https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -o miniconda.sh
   > bash miniconda.sh -b -p ${ISCEHOME}/python/miniconda3
   > touch ${ISCEHOME}/python/miniconda3/conda-meta/pinned
   > export PATH=${ISCEHOME}/python/miniconda3/bin:$PATH
   > export LD_LIBRARY_PATH=${ISCEHOME}/python/miniconda3/lib:$LD_LIBRARY_PATH
   > conda config --set show_channel_urls True
   > conda update --all
   > conda install --file ${ISCEHOME}/python/requirements.txt

3. (Optional) On some systems, it may be necessary to activate the conda root environment
   in order to export important environment variables used by make, cmake, etc.
   To activate the environment, use:

   > . ${ISCEHOME}/python/miniconda3/bin/activate root
   

Install ISCE from source

In this section we will walk through the directory setup and build system instructions for installing ISCE. ISCE can be built with 2 different build systems

1. mm
2. cmake.

In this set of instructions, we focus on cmake as it is already available via standard package managers.

Step 1: Get latest version of ISCE source

Option 1: Checkout latest version from git

1. Ensure that you are in the source folder

   > cd ${ISCEHOME}/tools/isce/src

2. Check out the latest version of the source code from git

   > git clone https://github-fn.jpl.nasa.gov/isce-3/isce

3. Ensure you are building the branch that you want to use.
   For example, if you want to build the develop branch

   > cd isce
   > git checkout develop

Option 2: Get the latest tarball

1. Ensure that you are in the source folder

   > cd ${ISCEHOME}/tools/isce/src

2. Unpack the tarball.

   > tar xjbf isce.tar.bz2

Step 2: Build the software

1. For our cmake build, we follow the practice of building outside of the source parent directory.
   To that end, we first create a temporary build directory:

   > cd ${ISCEHOME}/tools/isce
   > mkdir build
   > cd build

2. Ensure that you have activated the scl environment (Centos), conda and set
   environment variables needed by pyre following instructions provided above.

   Note: for some operating systems, if you wish to build the CUDA extensions, you may need to run

   export CUDACXX=/usr/local/cuda/bin/nvcc

3. Run cmake with the correct inputs and compiler flags

   > CC=gcc CXX=g++ cmake -DCMAKE_INSTALL_PREFIX=${ISCEHOME}/tools/isce/install ${ISCEHOME}/tools/isce/src/isce

   or

   > CC=${ISCEHOME}/tools/gcc7/bin/gcc CXX=${ISCEHOME}/tools/gcc7/bin/g++ \
     cmake -DCMAKE_INSTALL_PREFIX=${ISCEHOME}/tools/isce/install \
           ${ISCEHOME}/tools/isce/src/isce

   Other optional arguments can be added to the cmake line

   Additional cmake options

   Option	Description
   -DWITH_CUDA=OFF	Do not attempt to detect CUDA support (default "Auto" will auto-detect CUDA toolchain, but can be explicitly required/ignored with ON/OFF)
   -DMEMORY_CHECK_COMMAND=PATH_TO_VALGRIND_EXECUTABLE <br> -DMEMORYCHECK_COMMAND_OPTIONS="--trace-children=yes --leak-check=full --track-origins=yes" <br> -DCMAKE_BUILD_TYPE=Debug
   	Run tests with "-T memcheck" to check for memory leaks.
   	valgrind needs to be installed.
   -DPYTHON_EXECUTABLE:FILENAME=<path_to_python_exe>	Pass this argument if installing to a python virtual environment
   -DCMAKE_BUILD_TYPE=RelWithDebInfo	Build with optimization flags with release. Default is to build in debug mode

   Following env variables can also be used to control cmake behavior. Use these settings if cmake fails to identify the right compilers or install locations of dependencies.

   Additional environment variables impacting cmake

   Variable	Description
   CC	Path to the C compiler
   CXX	Path to the C++ compiler
   GDAL_ROOT	Path to location of gdal installation. With anaconda, ${ISCEHOME}/python/miniconda3.

4. Build the software

   > make VERBOSE=ON

5. Run the unit tests to ensure that software was built correctly

   > ctest

Step 3: Install and set environment variables

1. Ensure that you are in the build folder

   > cd ${ISCEHOME}/tools/isce/build

2. Install the software

   > make install

3. Setup the environment variables.

   Environment variables to set after installing ISCE

   Variable	Setting	Description
   PATH	$PATH:${ISCEHOME}/tools/isce/install/bin	For executables installed by ISCE
   PYTHONPATH	$PYTHONPATH:${ISCEHOME}/tools/isce/install/packages	ISCE python package
   LD_LIBRARY_PATH	$LD_LIBRARY_PATH:${ISCEHOME}/tools/isce/install/lib	Shared libraries built by ISCE

   We also recommend setting these environment variables in your appropriate .bashrc or .bash_profile
   file to avoid having to set them for each new session. For example:

   # .bash_profile
   
   # Get the aliases and functions
   if [ -f ~/.bashrc ]; then
   . ~/.bashrc
   fi
   
   # User specific environment and startup programs
   
   # miniconda3
   export PATH=${ISCEHOME}/python/miniconda3/bin:$PATH
   export LD_LIBRARY_PATH=${ISCEHOME}/python/miniconda3/lib:$LD_LIBRARY_PATH
   
   # cuda compiler
   export CUDACXX=/usr/local/cuda/bin/nvcc
   # cuda host compiler
   export CUDAHOSTCXX=/usr/bin/gcc-6
   
   # isce
   export PATH=$PATH:${ISCEHOME}/tools/isce/install/bin
   export PYTHONPATH=$PYTHONPATH:${ISCEHOME}/tools/isce/install/packages
   export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${ISCEHOME}/tools/isce/install/lib