====== Ice Sheet & Sea Level System Model ======

> ISSM is open source and is funded by the NASA Cryosphere, IceBridge Research and MAP (Modeling Analysis and Prediction) programs, JPL R&TD (Research, Technology and Development) and the National Science Foundation.
>
> Large scale ice flow models are necessary that can accurately model the evolution of Greenland and Antarctica in a warming climate. In order to achieve this goal, and improve projections of future sea level rise, ISSM relies on state of the art technologies.

  * For more information: https://issm.jpl.nasa.gov/
  * User guide: https://issmteam.github.io/ISSM-Documentation/using-issm/
  * Github: https://github.com/ISSMteam/ISSM

----

===== Running ISSM on Comet =====

As ISSM has a large number of dependencies, including //specific// versions of Python, as such it has been installed on Comet as an **Apptainer** //container image//.

The ISSM container is stored in the ''/nobackup/shared/containers'' directory and is accessible to __all__ users of Comet. You do //not// need to take a copy of the container file; it should be left in its original location.

You can find the container files here:

   * ''/nobackup/shared/containers/issm.2026.03.sif''

We //normally// recommend using the latest version of the container, in the case of ISSM, the version numbers represent the date the container was created.

<WRAP round box info>
**Container Image Versions**

We //may// reference a specific container file, such as **issm.2026.03.sif**, but you should always check whether this is the most recent version of the container available. Simply ''ls'' the ''/nobackup/shared/containers'' directory and you will be able to see if there are any newer versions listed.
</WRAP>

We have provided a convenience script that will automate **all** of steps needed to run applications inside the container as well as access your ''$HOME'',  ''/scratch'' and ''/nobackup'' directories to just two simple commands.

   * ''/nobackup/shared/containers/issm.2026.03.sh''

<WRAP round box info half>
There is a corresponding ''.sh'' script for //each version// of the container image we make available.
</WRAP>

Just ''source'' this file and it will take care of loading ''apptainer'', setting up your ''bind'' directories and calling the ''exec'' command for you - and give you a single command called ''container.run'' (instead of the really long //apptainer exec// command) to then //run// anything you want inside the container, for example to see the help page for ''issm.exe'':

<code lang=bash>
$ source /nobackup/shared/containers/issm.2026.03.sh
$ container.run issm.exe -help

──────────────────────────────────────────────────────────────────────
Ice-sheet and Sea-level System Model (ISSM) version 2026.1
          GitHub: https://github.com/ISSMteam/ISSM/
   Documentation: https://issmteam.github.io/ISSM-Documentation/
──────────────────────────────────────────────────────────────────────
----------------------------------------
Petsc Release Version 3.22.3, Jan 29, 2025 
       The PETSc Team
    petsc-maint@mcs.anl.gov
 https://petsc.org/
See https://petsc.org/release/changes for recent updates.
See https://petsc.org/release/faq for problems.
See https://petsc.org/release/manualpages for help.
Libraries linked from /home/jenkins/workspace/Debian_Linux-Binaries-Python_3/externalpackages/petsc/install/lib
----------------------------------------
Options for all PETSc programs:
 -version: prints PETSc version
...
$
</code>

----

===== Basic use of ISSM commands =====

ISSM is installed to ''/opt/ISSM-Linux-Python-3/bin'' //within// the container and this is added to the ''$PATH'' variable so that you do not need to enter the full path to the commands, simply call ''container.run'' with the ISSM command you want to run as per the example below.

<code lang=bash>
$ source /nobackup/shared/containers/issm.2026.03.sh
$ container.run issm.exe
</code>

   * See https://issmteam.github.io/ISSM-Documentation/using-issm/

----

===== Accessing ISSM in Python =====

You need to use the version of Python installed //within// the ISSM container to run your scripts if you intend to use the ISSM Python modules.

Following the [[https://issmteam.github.io/ISSM-Documentation/using-issm/getting-started/loading-issm|ISSM getting started]] guide we can verify ISSM Python modules are available with the following commands:

<code lang=bash>
$ source /nobackup/shared/containers/issm.2026.03.sh
$ container.run python
</code>

The Python runtime //inside// the container will start:

<code lang=python>
Python 3.11.0rc1 (main, Aug 12 2022, 10:02:14) [GCC 11.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>
</code> 

Now enter the following:

<code lang=python>
from issmversion import issmversion
</code>

The normal output from ISSM should be shown, indicating that the Python modules are working correctly:

<code lang=python> 
Ice-sheet and Sea-level System Model (ISSM) Version 2026.1
(website: https://issmteam.github.io/ISSM-Documentation/ contact: https://github.com/ISSMteam/ISSM/)
 
Build date: Fri Mar 20 06:13:00 PDT 2026
Copyright (c) 2009-2026 California Institute of Technology (3-Clause BSD License)
>>>
</code>

Assuming you have written a Python script called ''myscript.py'' to use the ISSM Python modules/functions, and it is in your home directory, you can use ''python'' inside the ISSM container to run it as follows:

<code lang=bash>
$ source /nobackup/shared/containers/issm.2026.03.sh
$ container.run python $HOME/myscript.py
</code>

<WRAP round box tip>
Note that you //do not// have to set up the ''$ISSM_DIR'' environment variable, alter the ''$PYTHONPATH'' or any of the other initial //setup// steps as found in the Getting Started guide - this is all done for you within the container.
</WRAP>
----
===== Accessing Data =====

As long as you use the ''container.run'' method to launch the applications, you will automatically be able to read and write to files in your ''$HOME'', ''/scratch'' and ''/nobackup'' directories. 

If you run any of the applications inside the container manually, without using the ''container.run'' helper you will need to use the ''--bind'' argument to ''apptainer'' to ensure that all relevant directories are exposed within the container.

Do remember that the container filesystem itself cannot be changed - so you won't be able to write or update to ''/usr/local'', ''/opt'', ''/etc'' or any other internal folders - keep output directories restricted to the three areas listed above.

----

===== Building ISSM for Comet =====

<WRAP round box important>
**Important!**

The information in this section is for RSE HPC admin staff or users who are interested in how the software is installed. If you are only interested in //using// ISSM, stop reading now.
</WRAP>

**Build script**

<code lang=bash title=issm.build.sh>
#!/bin/bash
IMAGE_DATE=`date +%Y.%m`

echo "Loading modules..."
module load apptainer

echo ""
echo "Building container..."
export APPTAINER_TMPDIR=/scratch

echo ""
echo "Container will have date suffix $IMAGE_DATE"

SOURCE_DIR=`pwd`
apptainer build --bind $SOURCE_DIR:/mnt issm.$IMAGE_DATE.sif issm.def 2>&1 | tee issm.log
</code>

**Container definition**

Note that we use //Ubuntu 22// instead of the more recent //Ubuntu 24//, as ISSM binaries are built against Python 3.11 - which is not available in the more recent release of Ubuntu.

<code lang=bash title=issm.def>
Bootstrap: docker
From: ubuntu:jammy

####################################################################
#
# ISSM Container
# ==================
# This is a runtime environment for the Ice-sheet and Sea-level System Model
# Please see: 
#	https://hpc.researchcomputing.ncl.ac.uk/dokuwiki/dokuwiki/doku.php?id=advanced:software:issm
#
####################################################################

%post
    # Prevent interactive prompts
    export DEBIAN_FRONTEND=noninteractive

####################################################################
#
# Basic system packages
#
####################################################################

	# Update & install only necessary packages
	apt-get update
	apt-get install -y apt-utils wget tar aptitude less openmpi-bin openmpi-common vim python3.11-full python3.11-venv libpython3.11 python3-pip
	
	# Make Python3.11 the default, as needed by ISSM
	ln -sf /usr/bin/python3.11 /usr/bin/python3
	ln -sf /usr/bin/python3 /usr/bin/python
	
	# Clean up APT cache to save space
	apt-get clean 

	# Any Python modules installed via pip go here
	# pip install NAME --break-system-packages
	
	# Remove any Python cache files after pip
	pip cache purge

#################################################################################
#
# This is all the custom stuff needed to build the various ISSM tools
#
#################################################################################

	# Src and opt 
	mkdir -p /src/zipped
	mkdir -p /opt/bin

	echo ""
	echo "INSTALL ISSM"
	echo "============"
	echo ""
	wget -q https://ross.ics.uci.edu/ISSM-Linux-Python-3.tar.gz -O /src/zipped/ISSM-Linux-Python-3.tar.gz
	cd /opt
	tar -zxf /src/zipped/ISSM-Linux-Python-3.tar.gz
	
	# Remove all src packages
	echo ""
	echo "FINAL CLEAN UP"
	echo "=============="
	echo ""
	cd /
	rm -rf /src
	pip cache purge

%environment
	export ISSM_DIR=/opt/ISSM-Linux-Python-3
	export PYTHONPATH=$ISSM_DIR/bin:$ISSM_DIR/lib:$ISSM_DIR/share:$ISSM_DIR/share/proj:$PYTHONPATH
	export PATH=/opt/bin:$ISSM_DIR/bin:$PATH

%runscript
</code>

**Helper script**

<code lang=bash title=issm.sh>
#!/bin/bash

module load apptainer

IMAGE_NAME=/nobackup/shared/containers/issm.2026.03.sif

container.run() {
    # Run a command inside the container...
    # automatically bind the /scratch and /nobackup dirs
    # pass through any additional parameters given on the command line
    apptainer exec --bind /scratch:/scratch --bind /nobackup:/nobackup ${IMAGE_NAME} $@
}
</code>

----

[[:advanced:software|Back to software]]