Linux/Mac source installation

A Note About HPC Environments

MATLAB and Python are used only for pre- and post-processing and not required to do actual simulations. The strategy that we generally employ is to install one copy of ISSM on a local machine and another on the cluster where only the binaries (e.g. issm.exe) are compiled. We can achieve this by using the -without-wrappers option. The MATLAB or Python interface can then send the binary input files to the cluster and fetch the output file once the run is completed. See our parallel computing page to learn more.

A Note About Anaconda

Anaconda environments can cause all sorts of toolchain conflicts at configuration and compile time that are hard to diagnose. If you use Anaconda and are having issues compiling the external packages, you might try disabling your Anaconda environment with,

conda deactivate

If you have an environment other than the default loaded, you can disable it with,

conda deactivate <ENV_NAME>

If disabling your Anaconda environment resolves configuration/compilation issues, you might consider disabling it by default in your shell profile (after the conda initialize block).

Environment Variables

The compilation of ISSM requires several environment variables. Add the following lines in your shell configuration file,

  • ~/.bashrc, ~/.bash_profile, or ~/.zshrc
export ISSM_DIR=<ISSM_PATH> source $ISSM_DIR/etc/environment.sh
  • ~/.cshrc
setenv ISSM_DIR <ISSM_PATH> source $ISSM_DIR/etc/environment.csh

where <ISSM_PATH> is the path to the ISSM parent directory (ex: /home/<user>/svn/issm/trunk).

macOS

In order to install ISSM on macOS, you will need the Command Line Tools, which can be installed using,

xcode-select --install

You may also be able to use the commands that come with Xcode if you have that installed, but if you do not use Xcode otherwise as an IDE, we recommend only installing the Command Line Tools.

NOTE: Having both the Command Line Tools and Xcode installed can cause toolchain conflicts in some cases. If you are experiencing hard to debug issues during configuration or compilation, try the following, which will select the Command Line Tools as the default,

sudo xcode-select --switch /Library/Developer/CommandLineTools

Unfortunately both the Command Line Tools and Xcode do not contain a Fortran compiler, which is required for various external packages. Therefore, you will have to install one. GFortran precompiled binaries and instructions for building from source code are available on the GCC Wiki. There is also a well-maintained GitHub repository of gfortran for macOS installers. Alternatively, gfortran can be installed via a package manager such as Homebrew.

External package installation

All ISSM external packages are located in the $ISSM_DIR/externalpackages/. Several packages may be installed depending on what users want to do. The following packages and installation scripts are recommended for a standard installation of ISSM on Linux,

autotools install-linux.sh cmake install.sh petsc install-3.14-linux.sh triangle install-linux.sh m1qn3 install.sh

On Intel-based Macs, the installation scripts are nearly the same,

autotools install-mac.sh cmake install.sh petsc install-3.14-mac.sh triangle install-mac.sh m1qn3 install.sh

Likewise, for Silicon-based Macs, we use,

autotools install-mac.sh cmake install.sh petsc install-3.17-mac-silicon.sh triangle install-mac.sh m1qn3 install.sh

For each package, different installation scripts may exist depending on the version to be installed and the machine operating system. Users should use the installation script that is the closest to their environment. For example,

$ cd $ISSM_DIR/externalpackages/autotools $ ./install.sh

There is no guarantee the compilation will work on all systems. Some tweaking of the installation script may be involved, especially the configuration part of the install. Some troubleshooting information is available on our FAQ page). Feel free to post questions to the ISSM Forum regarding the configuration and installation of external packages and/or configuring ISSM for extended features such as Dakota and solid earth.

NOTE: After the installation of each package, one should source the ISSM environment,

$ source $ISSM_DIR/etc/environment.sh

Python Interface

There are two scripting language interfaces to ISSM: MATLAB (preferred) or Python (not fully supported). To run ISSM with a Python interface, you will need to install a few packages.

NOTE: There are various methods for installing the required packages. The following is our suggestion.

Linux (using APT)

First, to correct a missing Python.h,

sudo apt-get install python-dev python3-dev

Python 2 and 3 can be installed with,

sudo apt-get install python-minimal python3-minimal

Tkinter can be installed with,

sudo apt-get install python-tk python3-tk

Install pip with,

sudo apt-get install python-pip python3-pip

Then, use pip to install NumPy, SciPy, and dependencies,

python -m pip install --user numpy scipy matplotlib nose python3 -m pip install --user numpy scipy matplotlib nose

macOS

If NumPy and SciPy are not already installed (they should be with the default installation of Python), one can use pip:

First, we need to install pip if it has not been installed already,

sudo easy_install pip

Then, we can install NumPy, SciPy, and other libs with,

python -m pip install --user numpy scipy matplotlib nose

ISSM compilation

ISSM relies on autotools to make source code packages portable to many Unix-like systems. The last step consists of generating the Makefiles needed to compile ISSM. First, ISSM must be reconfigured,

$ cd $ISSM_DIR $ autoreconf -ivf

ISSM can then be configured. You need to create a configuration file called configure.sh and placed in $ISSM_DIR. Here is an example of configuration script for a macOS machine with the MATLAB interface (you will need to change the path to MATLAB. We are using /Applications/MATLAB_R2023b.app/ as an example).

./configure \ --prefix=${ISSM_DIR} \ --with-numthreads=2 \ --with-matlab-dir="/Applications/MATLAB_R2023b.app" \ --with-fortran-lib="-L/usr/local/gfortran/lib -lgfortran" \ --with-mpi-include="${ISSM_DIR}/externalpackages/petsc/install/include" \ --with-mpi-libflags="-L${ISSM_DIR}/externalpackages/petsc/install/lib -lmpi -lmpicxx -lmpifort" \ --with-metis-dir="${ISSM_DIR}/externalpackages/petsc/install" \ --with-parmetis-dir="${ISSM_DIR}/externalpackages/petsc/install" \ --with-blas-lapack-dir="${ISSM_DIR}/externalpackages/petsc/install" \ --with-scalapack-dir="${ISSM_DIR}/externalpackages/petsc/install" \ --with-mumps-dir="${ISSM_DIR}/externalpackages/petsc/install" \ --with-petsc-dir="${ISSM_DIR}/externalpackages/petsc/install" \ --with-triangle-dir="${ISSM_DIR}/externalpackages/triangle/install" \ --with-m1qn3-dir="${ISSM_DIR}/externalpackages/m1qn3/install"

For the Python interface, it should look like:

./configure \ --prefix="${ISSM_DIR}" \ --with-python-version=3.9 \ --with-python-dir="/usr" \ --with-python-numpy-dir="${HOME}/.local/usr/lib/python3.9/dist-packages/numpy" \ --with-fortran-lib="-L/usr/local/gfortran/lib -lgfortran" \ --with-mpi-include="${ISSM_DIR}/externalpackages/petsc/install/include" \ --with-mpi-libflags="-L${ISSM_DIR}/externalpackages/petsc/install/lib -lmpi -lmpicxx -lmpifort" \ --with-metis-dir="${ISSM_DIR}/externalpackages/petsc/install" \ --with-parmetis-dir="${ISSM_DIR}/externalpackages/petsc/install" \ --with-blas-lapack-dir="${ISSM_DIR}/externalpackages/petsc/install" \ --with-scalapack-dir="${ISSM_DIR}/externalpackages/petsc/install" \ --with-mumps-dir="${ISSM_DIR}/externalpackages/petsc/install" \ --with-petsc-dir="${ISSM_DIR}/externalpackages/petsc/install" \ --with-triangle-dir="${ISSM_DIR}/externalpackages/triangle/install" \ --with-m1qn3-dir="${ISSM_DIR}/externalpackages/m1qn3/install"

NOTE: If you get the following error: ld: library not found for -lflapack, remove the line -with-blas-lapack-dir (generally on macOS).

For most platforms, you might need to make some adjustments to the configuration options mentioned above. Some other examples are provided on the ISSM Trac Wiki.

If the configuration completed without any errors, ISSM can now be compiled,

$ cd $ISSM_DIR $ make $ make install

ISSM installation is done!