This guide provides instructions to install ISCE2 with Anaconda/Miniconda on a Linux/MacOS machine. NOTE: this is not the official installation guide. It only serves to help users to install ISCE2 on some common and most recent platforms. Please check the ISCE2 page for official guides and tutorials.
- Linux with Anaconda3 : cmake with GPU support (updated December 2023)
- MacOSX with Anaconda3 and homebrew: Apple Silicon (updated December 2023))
- MacOSX with Macports : Apple Silicon with mdx (updated Sepetember 2023)
- Linux with Anaconda3 : scons (not updated)
- MacOSX with Anaconda3 : Intel (not updated)
-
Prepare a conda or conda virtual environment
conda create -n isce2 conda activate isce2
(Any python version 3.7 - 3.11 should work).
The following steps will install isce2 to $CONDA_PREFIX.
echo $CONDA_PREFIX
-
Install required packages
conda install -c conda-forge git cmake cython gdal h5py libgdal pytest numpy fftw scipy pybind11 shapely pip install opencv-python
opencv
has complex dependencies, which causes long delay to the conda compatibility check. We recommend installing it with pip
.
To compile/install mdx, you will also need
conda install -c conda-forge openmotif openmotif-dev xorg-libx11 xorg-libxt xorg-libxmu xorg-libxft libiconv xorg-libxrender xorg-libxau xorg-libxdmcp poppler
NOTE: it seems that openmotif
package is not actively maintained in conda. If you experience long delays in this step, please STOP and just use linux system installed openmotif. You may use the command ldconfig -p | grep libXm
to check whether it exists. If not, install openmotif by
# Ubuntu/Debian
sudo apt install libxm4
# Redhat CentOS
yum install motif, motif-devel
Compilers. GNU compilers coming with the system are recommended; GCC 4.8 - 13 are supported. ONly if you don't have access to a system installed compiler,) you may use conda gnu compilers,
conda install gcc_linux-64 gxx_linux-64 gfortran_linux-64
To use GPU-accelerated modules, you will need a CUDA compiler, which is usually located at /usr/local/cuda
or can be loaded by module load cuda
. Note that CUDA compiler (nvcc
) may have restrictions on host compilers, see CUDA Documentaion for more details. Note also that CUDA 12 has dropped support for devices < sm_50, such as K40. Please use CUDA 11 for these old devices.
-
Download the source package
mkdir -p $HOME/tools/src cd $HOME/tools/src git clone https://github.com/isce-framework/isce2.git
-
Compile and install isce2
cd $HOME/tools/src/isce2 # create a build directory mkdir build && cd build # use a symbolic link instead of specify -DPYTHON_MODULE_DIR=lib/python3.xx/site-packages ln -sf `python3 -c 'import site; print(site.getsitepackages()[0])'` $CONDA_PREFIX/packages # run cmake config cmake .. -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX \ -DCMAKE_CUDA_ARCHITECTURES=native \ -DCMAKE_PREFIX_PATH=${CONDA_PREFIX} \ -DCMAKE_BUILD_TYPE=Release # compile and install make -j && make install
-
Some common issues
-DCMAKE_CUDA_ARCHITECTURES=native
the native, or auto-detect gpu architecture option requres cmake >= 3.24. If you see a message likenvcc fatal : Unsupported gpu architecture 'compute_'
, you are using an old version of cmake and need to change native to your targeted gpu architecture(s). See details below.- Also make sure that
cmake
has identified the correct python interpreter from conda. Sometimes, it uses the system installed python instead. In this case, you may guide find_python by adding-DPython_EXECUTABLE=`which python3`
.
-
DCMAKE_INSTALL_PREFIX
is where the package is to be installed. Here, we choose to install to the conda venv directly ($CONDA_PREFIX) such that the paths to isce2 commands/scripts are automatically set up, like other conda packages. -
DPYTHON_MODULE_DIR
(no longer needed with the symbolic link) is the directory to install Python scripts, defined relative to theDCMAKE_INSTALL_PREFIX
directory. Please check your conda venv python3 version, and set it accordingly, e.g., python3.7 instead of python3.9. One method to check the site-packages directory for your Python version is to run the commandpython3 -c 'import site; print(site.getsitepackages())'
-
DCMAKE_CUDA_ARCHITECTURES
targets optimizing the GPU code for a specific GPU architecture, or in terms of the CUDA Compute Capability, e.g., 60 for P100, 70 for V100, 80 for A100, 90 for H100, ... If the GPU is installed on the same machine you are compiling the code, you may simply useDCMAKE_CUDA_ARCHITECTURES=native
to auto-config. If you plan to run the code on multiple architectures, use a list such asDCMAKE_CUDA_ARCHITECTURES="60;70;86"
, see CMake Manual for more details. -
DCMAKE_PREFIX_PATH
is for search path(s) of dependencies, such as gdal, fftw. Since we installed all dependencies through conda, we use ${CONDA_PREFIX}. -
DCMAKE_BUILD_TYPE=(None, Debug, Release)
. Some isce2 modules (e.g. PyCuAmpcor) have debugging features which are turned on/off by the -DNDEBUG compilation flag. This flag is not included in Debug build type or not specified, i.e., debugging features are on. It is included in Release build type, and therefore debugging features are turned off. For end users, please use Release build type. -
If cmake cannot locate the desired compilers correctly, you can enforce the choice of compilers by adding
-DCMAKE_C_COMPILER=/path/to/gcc -DCMAKE_CXX_COMPILER=/path/to/g++ -DCMAKE_Fortran_COMPILER=/path/to/gfortran
-
If something is wrong in the compilation and you would like to check the details
make VERBOSE=1
- Check and Test
You may check whether ISCE2 is properly installed by
cd $CONDA_PREFIX/bin
ls -ltr
# you should see mdx, and other python apps are installed
cd ../lib/python3.x/site-packages
ls -ltr
# you should see isce2 and an additional link isce
You may try to run
python3 -c 'import isce'
topsApp.py -h
...
Next time, all you need to do to load isce2 is to
codna activate # if you install to the base
conda activate isce2 # if you install to an isce2 venv.
By default, the CUDA modules run on GPU device 0 (currently only one GPU per task is supported). If there are multiple tasks or multiple users sharing the same device, the program will run slow or even crash. If you have multiple GPUs installed (run nvidia-smi
to check), you may spread your tasks to different GPUs, by using CUDA_VISIBLE_DEVICES=n
to select the device, where n=0,1,...
up to the number of GPUs installed. For example, to use device 2 (third GPU),
export CUDA_VISIABLE_DEVICES=2
topsApp.py ...
# or one line
CUDA_VISIBLE_DEVICES=2 topsApp.py ...
Note: SCons with Conda doesn't work on Mac. You may need to use macports.
Note: If you plan to use Linux provided packages instead of Conda, please follow Ubuntu 18.04 example to create a SConfigISCE
config file.
-
Install Anaconda or Minoconda. If you only run isce2 with venv, miniconda is recommended.
-
If you prefer, prepare a conda virtual environment
conda create -n isce2 python=3.8 conda activate isce2
-
Install required packages
conda install -c conda-forge git scons cython gdal h5py libgdal pytest numpy fftw scipy opencv pybind11 shapely
To compile/install mdx, you will also need
conda install -c conda-forge openmotif openmotif-dev xorg-libx11 xorg-libxt xorg-libxmu xorg-libxft libiconv xorg-libxrender xorg-libxau xorg-libxdmcp
You will need to make a symbolic link for cython3,
cd $CONDA_PREFIX/bin
ln -sf cython cython3
If you plan to use conda installed GNU compilers (note that currently there are some compatibility issues of conda compiler with Redhat 7 systems, don't install gcc_linux-64, .... If you already made the following links, please delete them.)
ln -sf x86_64-conda_cos6-linux-gnu-gcc gcc
ln -sf x86_64-conda_cos6-linux-gnu-g++ g++
ln -sf x86_64-conda_cos6-linux-gnu-gfortran gfortran
ln -sf x86_64-conda_cos6-linux-gnu-ld ld
# for some conda-forge builds (seems no longer an issue with python3.8)
cd $CONDA_PREFIX/lib
ln -sf libzstd.so.1.3.7 libzstd.so.1
-
Download isce2 for GitHub or prepare your own version
# create a directory to save source files mkdir -p ${HOME}/tools/src cd {$HOME}/tools/src # glone a copy from github git clone https://github.com/isce-framework/isce2
The command shall pull a GitHub version of isce2 to your ${HOME}/tools/src/isce2
directory.
-
Configure a
SConfigISCE
file under, e.g.${HOME}/.isce
directoryPRJ_SCONS_BUILD=$HOME/build/isce_build PRJ_SCONS_INSTALL=$ISCE_HOME LIBPATH=$CONDA_PREFIX/lib CPPPATH=$CONDA_PREFIX/include $CONDA_PREFIX/include/python3.8/ $CONDA_PREFIX/lib/python3.8/site-packages/numpy/core/include $CONDA_PREFIX/include/opencv4 FORTRAN=gfortran CC=gcc CXX=g++ FORTRANPATH=$CONDA_PREFIX/include MOTIFLIBPATH=$CONDA_PREFIX/lib X11LIBPATH=$CONDA_PREFIX/lib MOTIFINCPATH=$CONDA_PREFIX/include X11INCPATH=$CONDA_PREFIX/include RPATH=$CONDA_PREFIX/lib ENABLE_CUDA = True CUDA_TOOLKIT_PATH=/usr/local/cuda # use 'which nvcc' to verify
PRJ_SCONS_BUILD
is a directory to save temporary compiled filesPRJ_SCONS_INSTALL
is where the isce2 will be installed. We use a$ISCE_HOME
to be defined laterLIBPATH
is where to look for the shared libraries, such as gdal, fftwCPPPATH
is where to look for C/C++ head files (#include) for librariesFORTRAN
,CC
,CXX
are the Fortran/C/C++ compilers to be usedMOTIFLIBPATH
...X11INCPATH
are to set lib and include paths for motif and x11 libraries.- for Ubuntu 18.04, set
MOTIFLIBPATH1
andX11LIBPATH
to/usr/lib/x86_64-linux-gnu/
and setMOTIFINCPATH
andX11INCPATH
to/usr/include
. - for Redhat or CentOS 7, set
MOTIFLIBPATH1
andX11LIBPATH
to/lib64
and setMOTIFINCPATH
andX11INCPATH
to/usr/include
. - for conda installed packages, set them as
$CONDA_PREFIX/lib
and$CONDA_PREFIX/include
.
- for Ubuntu 18.04, set
ENABLE_CUDA
=True/False
whether to include some GPU/CUDA accelerated modules. If enabled, please also specifyCUDA_TOOLKIT_PATH
to where CUDA SDK is installed. Some manual configuration might be needed:- CUDA SDK Versions 9 and above are recommended.
- The CUDA compiler 9 & 10 by default targets NVIDIA GPUs with compute capability 3.5 (K40, K80). CUDA 11 uses sm_52 as default. If you prefer to compile CUDA code best suited to the GPU you have, find
env['ENABLESHAREDNVCCFLAG']
in${HOME}/tools/src/isce2/scons_tools/cuda.py
file, find the lineenv['ENABLESHAREDNVCCFLAG'] = '-std=c++11 -shared
, add-arch=sm_35
for K40/K80,-arch=sm_60
for P100,-arch=sm_61
for GTX1080,-arch=sm_70
for V100.
- Some settings for environment variables before compile/install. You need to specify three environment variables
CONDA_PREFIX
where Anaconda3 is installedISCE_HOME
where isce2 will be installedSCONS_CONFIG_DIR
where theSConfigISCE
is located. if they are not set. Check by, e.g.,echo $CONDA_PREFIX
.
For csh
,
setenv ISCE_HOME ${HOME}/tools/isce
setenv SCONS_CONFIG_DIR ${HOME}/.isce
and for bash
,
export ISCE_HOME=${HOME}/tools/isce
export SCONS_CONFIG_DIR=${HOME}/.isce
-
Compile/install isce2
cd ${HOME}/tools/src/isce2 scons install
If successful, you should obtain a compiled isce2 at $ISCE_HOME
or $HOME/tools/isce
.
Some common problems or questions:
- if you use conda installed X11 motif libraries, you might see an error
libXm.so not found
reported by scons. You may neglect and proceed; these libraries will be linked properly. But if you see error messages about gdal or fftw, please stop and check.
- Set up environment variables to load/usr isce2.
-
use environment module, .e.g.,
module load/unload isce2.mod
where an example ofisce2.mod
is provided below.#%Module module-whatis {Description: ISCE2-github} set root $HOME/tools/isce prepend-path LD_LIBRARY_PATH $root/lib prepend-path LIBRARY_PATH $root/lib prepend-path PATH $root/bin:$root/applications prepend-path PYTHONPATH $HOME/tools:$root:$root/applications:$root/components:$root/library setenv ISCE_HOME $root
Note that in order to import isce
from python, you need to use the isce
as the installation directory name and also set the directory where isce
is located (in above case, $HOME/tools
) to PYTHONPATH
.
-
use a resource file to load as
source isce2.rc
. Forcsh
,# isce2.cshrc setenv ISCE_HOME $HOME/tools/isce setenv PATH $ISCE_HOME/bin\:$ISCE_HOME/applications\:$PATH setenv LD_LIBRARY_PATH $ISCE_HOME/lib\:$LD_LIBRARY_PATH # check whether PYTHONPATH exists if ( ! $?PYTHONPATH ) then setenv PYTHONPATH $HOME\:$ISCE_HOME\:$ISCE_HOME/applications\:$ISCE_HOME/components\:$ISCE_HOME/library else setenv PYTHONPATH $HOME\:$ISCE_HOME\:$ISCE_HOME/applications\:$ISCE_HOME/components\:$ISCE_HOME/library\:$PYTHONPATH endif
For bash
,
# isce2.rc
export ISCE_HOME=$HOME/tools/isce
export PATH=$ISCE_HOME/bin:$ISCE_HOME/applications:$PATH
export LD_LIBRARY_PATH=$ISCE_HOME/lib:$LD_LIBRARY_PATH
export PYTHONPATH=$ISCE_HOME:$ISCE_HOME/applications:$ISCE_HOME/components:$ISCE_HOME/library:$HOME/tools:$PYTHONPATH
- Common questions/problems
(Testd on macOS Sonoma 14.1.2. This is the recommended method for MacOS - all packages are pre-compiled. However, after a major MacOS upgrade, e.g., from 13 to 14, a re-installation of Xcode Command Line Tools, conda, homebrew is recommended.)
- Install Xcode (or command line tools), Conda and gcc/g++/gfortran Compiler
Install an osx-arm64 build of Anaconda3 or Miniconda3 (recommended).
Taking miniconda as an example, you may follow the Quick Command Line Install method
mkdir -p ~/miniconda3
curl https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh -o ~/miniconda3/miniconda.sh
bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
rm -rf ~/miniconda3/miniconda.sh
Install Homebrew (the pkg installer is the easiest method, download from Homebrew Releases). For Apple Silions (osx-arm64), brew is installed to /opt/homebrew
.
export PATH="/opt/homebrew/bin:$PATH"
and then install gfortran (current version GCC 13.2)
brew install gfortran
If you need mdx (slc viewing software), install openmotif here (osx-arm64 version currently not available from conda)
brew install openmotif
Also install XQuartz.
-
Prepare a conda or conda virtual environment
conda create -n isce2 conda activate isce2
The following steps will install isce2 to $CONDA_PREFIX.
echo $CONDA_PREFIX
Make a link to make the installation path easier (-DPYTHON_MODULE_DIR
not longer need)
ln -sf `python3 -c 'import site; print(site.getsitepackages()[0])'` $CONDA_PREFIX/packages
-
Install required packages
conda install git cmake cython gdal h5py libgdal pytest numpy fftw scipy pybind11 shapely pip install opencv-python
opencv
has complex dependencies, which causes long delay to the conda compatibility check. We recommend installing it with pip
.
- Compile and install isce2
Download ISCE2 from github
git clone https://github.com/isce-framework/isce2.git
Compile ISCE2 with cmake,
cd isce2
mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX \
-DCMAKE_PREFIX_PATH=${CONDA_PREFIX} \
-DCMAKE_C_COMPILER="/opt/homebrew/bin/gcc-13" \
-DCMAKE_CXX_COMPILER="/opt/homebrew/bin/g++-13"
make -j # to use multiple threads
make install
We use gcc from homebrew instead of Apple Clang because of some compatibility issue (some source codes need to be updated).
- Config and run isce2
If you follow the above steps, ISCE2 packages are installed to $CONDA_PREFIX/packages/isce2. You will only need to add the path to stack apps,
export ISCE_HOME="$CONDA_PREFIX/packages/isce"
export PATH="$ISCE_HOME/applications:$PATH"
If you have installed ISCE2 to a custom directory, e.g., $HOME/apps/isce2
, with -DCMAKE_INSTALL_PREFIX=$HOME/apps/isce2
cmake option, you need to
export ISCE_INSTALL_ROOT="$HOME/apps/isce2"
export ISCE_HOME="$ISCE_INSTALL_ROOT/packages/isce"
export PATH="$ISCE_HOME/applications:$ISCE_INSTALL_ROOT/bin:$PATH"
export PYTHONPATH="$ISCE_INSTALL_ROOT/packages:$PYTHONPATH"
You may try the following to check whether ISCE2 has been properly installed,
python3 -c "import isce"
To use mdx, you will need XQuartz.
mdx.py xxxxx.slc
# show the slc picture (.xml description file needed)
Enjoy!
This is an old guide for Intel Macs (osx-64). It may also work for Apple Silicons with Rosetta 2, but may experience complexities on clang/gcc compilers for new versions of macOS.
Please follow the instructions for Linux. You may need to install xcode or command-line-tools. GPU modules are not supported for MacOSX, unless you use an external GPU with NVIDIA cards. You will then need to install NVIDIA driver and CUDA.
For Apple Silicon (M1, M2, ...), you may use the regular (x86_64) Conda releases (continue to work with Rosetta 2). Or you may install the native arm64 version from Anaconda, or Miniforge. However, openmotif is not currently supported by native arm64. If you need mdx, please use the x86_64 release with Rosetta 2.
Example with MacOSX 11.5.2 (Big Sur) and Apple Clang 12.0.5.
-
Prepare a conda or conda virtual environment
conda create -n isce2 conda activate isce2
The following steps will install isce2 to $CONDA_PREFIX.
echo $CONDA_PREFIX
-
Install required packages
conda install git cmake cython gdal h5py libgdal pytest numpy fftw scipy pybind11 pip install opencv
opencv
has complex dependencies, which causes long delay to the conda compatibility check. We recommend installing it with pip
.
To compile/install mdx, you will also need
conda install openmotif openmotif-dev xorg-libx11 xorg-libxt xorg-libxmu xorg-libxft libiconv xorg-libxrender xorg-libxau xorg-libxdmcp
- Compilers
If you already have Xcode installed,
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
which clang # show /usr/bin/clang
clang --version # Apple clang version 12.0.5 (clang-1205.0.22.11)
If not, you may install the full version of Xcode, or simply the Command Line Tools,
sudo xcode-select --install
sudo xcode-select --switch /Library/Developer/CommandLineTools
Install gfortran through brew
brew install gfortran
which gfortran # show /usr/local/bin/gfortran
gfortran --version # GNU Fortran (Homebrew GCC 11.2.0) 11.2.0
Or you may simply download the binary from HPC MacOSX: they have pre-compiled versions gfortran-x.x-bin.tar.gz
for all MacOSX systems, including Apple Silicon.
-
Compile and install isce2
cd $HOME/tools/src/isce2 mkdir build && cd build cmake .. -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX -DPYTHON_MODULE_DIR=lib/python3.9/site-packages -DCMAKE_PREFIX_PATH=${CONDA_PREFIX} make -j # to use multiple threads make install
Change cmake options if necessary, e.g., PYTHON_MODULE_DIR
to your installed python version. Enjoy!
Note that after each major MacOSX update, please try to update (or reinstall) Command Line Tools and update Conda.
You may notice warnings such as was built for newer macOS version (11.5) than being linked (11.0)
. It is in general safe to neglect these warnings. To suppress the warnings, you may add -DCMAKE_OSX_DEPLOYMENT_TARGET=11.5
to cmake command line.
(Tested on macOS Ventura 13.5.1)
- Install Xcode (or Command Line Tools) and Macports
Follow the Macports Guide to download and install Macports. All the files, by default, will be installed to /opt/local
. The PATH will also be automatically added to your .zprofile
or .profile
. If not, please run
export PATH="/opt/local/bin:/opt/local/sbin:$PATH"
It is a good idea to perform a update at first,
sudo port -v selfupdate
To run mdx (the SLC viewing software), please also install XQuartz.
- Install required packages
Compiler GCC/G++/Gfortran and OpenMP
sudo port install gcc12 libomp
sudo port select --set gcc mp-gcc12
Python and other libraries, (note: some additional python packages might be needed at runtime, you may always use sudo port install py311-xxxx
to install them later.)
sudo port install cmake python311 py311-cython py311-numpy py311-scipy py311-pybind11 pybind11 hdf5 py311-gdal fftw-3 fftw-3-single py311-opencv4-devel
sudo port select --set python python311
sudo port select --set python3 python311
sudo port select --set cython cython311
sudo port select --set gdal py311-gdal
sudo ln -sf `python3 -c 'import site; print(site.getsitepackages()[0])'` /opt/local/packages
(Optional) To use mdx, install Openmotif
sudo port install openmotif
- Install ISCE2
Download ISCE2 from GitHub
git clone https://github.com/isce-framework/isce2.git
Compile ISCE2 with cmake,
cd isce2
mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/opt/local \
-DCMAKE_C_COMPILER=/opt/local/bin/gcc \
-DCMAKE_CXX_COMPILER=/opt/local/bin/g++ \
-DCMAKE_PREFIX_PATH="/opt/local" \
-DOpenMP_C_FLAGS="-fopenmp=lomp" \
-DOpenMP_CXX_FLAGS="-fopenmp=lomp" \
-DOpenMP_C_LIB_NAMES="libomp" \
-DOpenMP_CXX_LIB_NAMES="libomp" \
-DOpenMP_libomp_LIBRARY="/opt/local/lib/libomp/libomp.dylib" \
-DOpenMP_CXX_LIB_NAMES="libomp" \
-DPython_ROOT_DIR="/opt/local/Library/Frameworks/Python.framework/Versions/3.11/"
make -j
sudo make install
(you may safely neglect the OpenCV warning.) Here, the installation path is set to /opt/local
, or MacPorts. You may choose a different directory, e.g., $HOME/apps/isce2
. But you will need to set PATH
and PYTHONPATH
manually by yourself.
- Config and run isce2
mdx
command is installed to /opt/local/bin
while the rest is installed to /opt/local/packages/isce2
(or the actual location /opt/local/Library/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages/isce2
. You may try the following to check whether ISCE2 has been properly installed,
python3 -c "import isce"
# return "Using default ISCE Path: /opt/local/Library/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages/isce".
To use some python apps, it is convenient to set up some environmental variables,
#isce2.rc
export ISCE_HOME="/opt/local/Library/Frameworks/Python.framework/Versions/3.11/lib/python3.11/site-packages/isce"
export PATH="$ISCE_HOME/applications:$PATH"
To use mdx, you will need XQuartz.
mdx.py xxxxx.slc
# show the slc picture (.xml description file needed)
(If you have a "cannot open DISPLAY" error, check here. )
Problems & Questions, please post on the Issue.