IceBin is a coupler for GCMs and Ice Models. It also provides capabilities for regridding with elevation classes, and with generalized grids.

See the file LICENSE for details on IceBin licensing.

We support building and running IceBin on Linux. IceBin should also work on Macintosh; however, there is not currently an easy way to build it.

IceBin is built with Spack, which requires a functional Python 2.6 or Python 2.7 on your system. Other standard build tools are assumed as well: make, git, etc. All other prerequisites are built with Spack.

The following installation was enough to prepare a bare Ubuntu 12.04 machine to build the IceBin software stack with Spack:

sudo apt-get install build-essential git curl m4 bison gettext libssl-dev libjpeg-dev libpthread-stubs0-dev libxau-dev libqt4-dev

In order to install IceBin's numerous dependencies, we recommend using Spack to install IceBin. Installing IceBin therefore involves three steps:

1. Install essential build tools (Spack, Environment Modules, GCC and git).
2. Use Spack to install IceBin and related packages.

Step 1 is general for any package one might install with Spack; whereas step 2 is specific to IceBin. Instructions for Linux are provided here; this has not been tested or debugged on Macintosh.

The build tools consist of Spack, which may be used to install Environment Modules, GCC and git if necessary. By using Spack to bootstrap the build envrionment, one ensures that an up-to-date version of the build tools is available, no matter what host operating system is being used. For more information on Spack, see: http://software.llnl.gov/spack

1. Download:

   cd ~
   # git clone git@github.com:citibeth/spack.git -b efischer/icebin
   git clone https://github.com/citibeth/spack.git -b efischer/icebin

2. Add to your .bashrc file:

   export SPACK_ROOT=$HOME/spack
   . $SPACK_ROOT/share/spack/setup-env.sh

3. Remove non-system stuff from your PATH, LD_LIBRARY_PATH and other environment variables, which can cause strange errors when building with Spack.

IceBin is known to work with GCC 4.9.3. In theory, it works with other C++11 compilers as well. Enter the following, to see what compilers Spack has found on your system:

spack compilers

This produces a file ~/.spack/compilers.yaml, which looks as follows on CentOS 7:

compilers:
  linux-x86_64:
    gcc@4.8.5:
      cc: /usr/bin/gcc
      cxx: /usr/bin/g++
      f77: /usr/bin/gfortran
      fc: /usr/bin/gfortran

NOTE: spack compilers does not always detect all installed compiilers. Make sure to check compilers.yaml after it has been auto-generated. Errors like "Compiler 'gcc@4.6' does not support compiling C++ programs" indicate a problem in compilers.yaml.

If you are happy with the compilers Spack found, you can proceed. Otherwise, you need to build GCC 4.9.3:

spack install gcc@4.9.3

Once that completes, add GCC 4.9.3 to the compilers.yaml file:

1. Identify the location of your new GCC with:

   spack location -i gcc@4.9.3

2. Add it to your compilers.yaml file, to look something like:

   compilers:
     linux-x86_64:
       gcc@4.8.5:
         cc: /usr/bin/gcc
         cxx: /usr/bin/g++
         f77: /usr/bin/gfortran
         fc: /usr/bin/gfortran
       gcc@4.9.3:
         cc: /home/rpfische/spack/opt/spack/linux-x86_64/gcc-4.8.5/gcc-4.9.3-layphctulnk3omsbjpzftqv6dlxpfe3d/bin/gcc
         cxx: /home/rpfische/spack/opt/spack/linux-x86_64/gcc-4.8.5/gcc-4.9.3-layphctulnk3omsbjpzftqv6dlxpfe3d/bin/g++
         f77: /home/rpfische/spack/opt/spack/linux-x86_64/gcc-4.8.5/gcc-4.9.3-layphctulnk3omsbjpzftqv6dlxpfe3d/bin/gfortran
         fc: /home/rpfische/spack/opt/spack/linux-x86_64/gcc-4.8.5/gcc-4.9.3-layphctulnk3omsbjpzftqv6dlxpfe3d/bin/gfortran

Create the file ~/.spack/packages.yaml. It can look like this for now:

packages:
    openssl:
        paths:
            openssl@system: /usr
        buildable: False

    all:
        compiler: [gcc@4.9.3]

A few things to note here:

1. The compiler section tells Spack which compilers to use, in preferred order.

2. The openssl section tells Spack to use the OS version of the OpenSSL library, rather than building one itself. This is for security reasons.

   If you choose this route, Spack will later give you spurious warnings that look like:

   ==> Warning: This installation depends on an old version of OpenSSL,
                which may have known security issues.
   ==> Warning: Consider updating to the latest version of this package.
   ==> Warning: More details at http://www.openssl.org

   You can safely ignore these warnings because they are false.

In order to use Spack's generated environment modules, you must have installed the Environment Modules package. On many Linux distributions, this can be installed from the vendor's repository. For example: `yum install environment-modules (Fedora/RHEL/CentOS). If your Linux distribution does not have Environment Modules, you can get it with Spack:

1. Install with:

   spack install environment-modules

2. Activate with:

   TMP=`tempfile`
   echo >$TMP
   MODULE_HOME=`spack location -i environment-modules`
    MODULE_VERSION=`ls -1 $MODULE_HOME/Modules | head -1`
    ${MODULE_HOME}/Modules/${MODULE_VERSION}/bin/add.modules <$TMP
    cp .bashrc $TMP
    echo "MODULE_VERSION=${MODULE_VERSION}" > .bashrc
    cat $TMP >>.bashrc

This adds to your .bashrc (or similar) files, enabling Environment Modules when you log in. Re-load your .bashrc (or log out and in again), and then test that the module command is found with:

module avail

Spack shell support allows Spack to work with Environment Modules. You can enable it by sourcing some files in the /share/spack directory. Add this to your .bashrc file, after the environment modules setup section:

export SPACK_ROOT=$HOME/spack
. $SPACK_ROOT/share/spack/setup-env.sh

You can put the above code in your .bashrc or .cshrc, and Spack's shell support will be available on the command line.

Log out and in again; you can now test this with a simple command like:

spack find
spack load gcc

You can also use environment modules directly, for example:

module avail

Older system-supplied versions of git do not provide features that are necessary today. You might wish to install the latest, greatest version of git. Do this with:

spack install git

Once Git is installed, make it available to Bash via:

spack load git

Older system-supplied versions of curl may not work to download some packages, particularly those using the https protocol. If this is the case, you may use a newer Spack-installed curl instead:

spack install curl
spack load curl

On Ubuntu 12.04, an updated binutils may be required to build some packages (eg, py-numpy):

spack load binutils

The IceBin library has many build and run dependencies. The instructions below will install them all.

Now it is time to tell Spack which compilers and package versions are preferred. Do this by adding to ~/.spack/packages.yaml so it looks like this:

packages:
    python:
        version: [3.5.1]
    py-cython:
        version: [0.23.4]
    py-proj:
        # Normal released version is buggy
        version: [1.9.5.1.1]

    netcdf-cxx4:
        version: [ecdf914]

    ibmisc:
        version: [0.1.0]

    icebin:
        version: [0.1.0]

    # Recommended for security reasons
    # Do not install OpenSSL as non-root user.
    openssl:
        paths:
            openssl@system: /usr
        buildable: False

    # Recommended, unless your system doesn't provide Qt4
    qt:
        paths:
            qt@system: /usr
        buildable: False

    all:
        compiler: [gcc@4.9.3]
        providers:
            mpi: [openmpi]
            blas: [openblas]
            lapack: [openblas]

IceBin produces a Python extension. The following Spack commands will install the Python modules necessary to build and run that extension:

spack install py-basemap ^py-matplotlib+gui+ipython ^py-numpy+blas+lapack ^openblas ^python@3:
spack install py-giss ^py-matplotlib+gui+ipython ^py-numpy+blas+lapack ^openblas ^python@3:
spack activate py-numpy

Activate modules you need to build IceBin:

module load spack module find --dependencies tcl py-numpy

spack install icebin@0.1.5 +gridgen +python ~coupler ~pism \
    ^ibmisc@0.1.2 ^netcdf+mpi ^eigen~suitesparse ^py-numpy+lapack \
    ^openblas ^python@3:

# Or to install just ibmisc
spack install ibmisc@0.1.2+python+netcdf ^netcdf-cxx4 ^netcdf+mpi ^eigen~suitesparse ^py-numpy+lapack ^openblas ^python@3:

Additionally, download the IceBin source code for testing purposes:

cd ~
git clone https://github.com/citibeth/icebin.git -b develop
cd icebin

The following command will load the Spack-installed packages needed for basic Python use of IceBin:

module load `spack module find tcl icebin netcdf cmake@3.5.1`
module load `spack module find --dependencies tcl py-basemap py-giss`

You can speed up shell startup by turning these into module load commands.

1. Cut-n-paste the script make_spackenv:

   #!/bin/sh
   #
   # Generate commands to load the Spack environment
   
   SPACKENV=$HOME/spackenv.sh
   
   spack module find --shell tcl git icebin@local ibmisc netcdf cmake@3.5.1 >$SPACKENV
   spack module find --dependencies --shell tcl py-basemap py-giss >>$SPACKENV

2. Add the following to your .bashrc file:

   source $HOME/spackenv.sh
   # Preferentially use your checked-out Python source
   export PYTHONPATH=$HOME/icebin/pylib:$PYTHONPATH

3. Run sh make_spackenv whenever your Spack installation changes (including right now).

The loaded packages may be tested as follows:

# These do not produce output
python3 -c 'import cython'
python3 -c 'import numpy'
python3 -c 'import scipy'
python3 -c 'import netCDF4'
python3 -c 'import matplotlib'
python3 -c 'from mpl_toolkits.basemap import Basemap'
python3 -c 'import ibmisc'
python3 -c 'import icebin'
python3 -c 'import giss'

# This does produce output...
python3 -c 'import pyproj; pyproj.test()'
which overlap

IceBin comes with two demonstrations of its regridding capabilities, in the folders tests/test_conserv and tests/test_issm. Each demo is self-contained, and is executed with the make command. The user may inspect makefile to determine the steps being demonstrated.

This tests all six regridding matrices between a ModelE (global) GCM grid and the SeaRISE (local) ice grid. Conservation is checked quantitatively. Plots are also generated showing the grids involved, and the regridded fields.

This tests regridding bewteen an ISSM mesh (I) and the SeaRISE Grid (A). Plots are generated showing the grids involved and regridded fields. However:

1. This software is not able to directly plot functions on an ISSM mesh. Only versions of the function on the SeaRISE grid are plotted at this time.
2. No quantiative measures of conservation are taken.
3. Construction of the regridding matrix AvI is currently only in Python. It has not been ported into the C++ code.