lzwei196/kiss---knowledge-infrastructure-for-scientific-simulation/issm

MANDATORY EXECUTION POLICY — READ BEFORE PROCEEDING

You MUST run the actual model binary or package described in this document.

If the model fails to import, compile, or execute, you MUST:

1. Check diagnostics/triplets.yaml for a matching error pattern

2. Try the fix suggested in the triplet's remedy section

3. If still failing, report the error to the user with full details

You MUST NOT substitute a simplified Python formula, regression equation,

or hand-coded approximation in place of the real model.

Before starting, run: python preflight_check.py (in this KI directory)

to verify that the model binary/package and required data are available.

DEBUGGING PROTOCOL — When something goes wrong, follow this order:

1. Check triplets — diagnostics/triplets.yaml may already cover this error

2. Read official docs — The model's own documentation for expected formats/units

3. Find working examples — Check outputs/ or the model's shipped test data

4. Fix the tool — With knowledge of what "correct" looks like

Do NOT write custom debug scripts. The answers are in the docs and examples.

<!-- KI-MAP:BEGIN (projected by generate_skill_map.py — edit the KI, not this table) -->

KI map — what to read, and when

Projected 2026-08-17 from the KI's actual contents — 9 components present. Refresh: `python3 ki_tools_common/generate_skill_map.py --ki_dir <this KI>`. <!-- KI-MAP:END -->

<!-- KI-TOOL-INDEX:BEGIN (projected by generate_skill_map.py — the discoverability contract: every public tool, exact path; PURPOSE stays human-authored elsewhere) -->

Executable tool index (projected — complete by construction)

Every public tool in this KI, by exact path. What each is FOR lives in the human-written Tool Inventory above; --help on any of these prints its arguments.

4 public tools; `_`-prefixed helpers and packaging files excluded. <!-- KI-TOOL-INDEX:END -->

ISSM (Ice-sheet and Sea-level System Model) — Knowledge Infrastructure

Package: hydrocraft-issm-cryosphere v1.0.0 Model: ISSM v2026.1 (Ice-sheet and Sea-level System Model) Created by: Jianyun Zhang Research Group, Hohai University Last updated: 2026-04-30 Stats: current tool, stage-doc and triplet counts: the KI map at the top of this file Validation status: synthetic_only (SquareIceShelf/SquareSheet NightlyRun benchmarks; domain Square.exp is a 5-point square, not a real glacier). Real-site validation: NOT DONE. Before claiming a real-site result, fetch BedMachine geometry + MEaSUREs surface velocity for a chosen target (e.g. Pine Island Glacier, Thwaites, Jakobshavn) and use tools/convert_geometry_to_issm.py to build a real md from them.

Data Preparation

Forcing data

Data Sources: Use from ki_tools_common.load_forcing import load_daily_forcing for CMFD/MSWX/NASA POWER.

Data Validation Reference: See data_ki/CMFD/SKILL.md for atmospheric forcing documentation. See data_ki/SNOTEL/SKILL.md ONLY for context. NOTE: point seasonal-snow SWE (e.g. SNOTEL) is NOT a valid ISSM validation target — ISSM has no snowpack SWE output (see NON-PRODUCIBLE VARIABLES below). See data_ki/BedMachine/SKILL.md for ice topography. See data_ki/MEaSUREs/SKILL.md for ice velocity.

Overview

This knowledge infrastructure enables autonomous ice sheet and sea-level simulations using ISSM (Ice-sheet and Sea-level System Model), a large-scale thermo-mechanical 2D/3D parallelized multi-purpose finite-element software developed at NASA JPL and UC Irvine.

What ISSM does: Finite-element model for ice sheet dynamics. Simulates:

• Ice flow velocity (SSA, SIA, HO, Full Stokes, L1L2, MOLHO formulations)

NON-PRODUCIBLE VARIABLES / VALID DOMAIN (dag gate guard)

ISSM is an unstructured-mesh finite-element ICE-SHEET DYNAMICS model. Its dag.yaml

outputs are: Vel/Vx/Vy/Vz (m/yr), Thickness/Surface/Base (m), Temperature (K),

grounding-line position, IceVolume/GroundedArea/TotalSmb, and relative sea level.

It produces NO point snowpack SWE (md.smb.mass_balance is a PRESCRIBED forcing

in m/yr ice-equivalent, not a computed seasonal snow water equivalent).

Valid real-site targets: glacier/ice-sheet surface velocity (MEaSUREs), ice

thickness / surface / base elevation (BedMachine), grounding-line position, and

ice volume / TotalSmb, over a polar or alpine GLACIATED domain in projected (meter)

coordinates. Any target whose observed variable is SWE/snowpack, or whose site has

no glacier/ice sheet (e.g. a mid-latitude SNOTEL site), is STRUCTURALLY INVALID and

MUST be rejected by the dag gate with no retry.

• Thermal evolution (cold-ice temperature or enthalpy formulation)
• Mass transport (thickness evolution via continuity equation)
• Transient dynamics (coupled time-stepping of velocity + thickness + temperature)
• Grounding line migration (floating vs grounded ice transitions)
• Calving and ice front evolution (von Mises, level-set, crevasse depth)
• Subglacial hydrology (GlaDS, Shakti, Shreve, PISM, DC models)
• Damage evolution (crevasse formation and propagation)
• Glacial isostatic adjustment (solid earth deformation, Love numbers)
• Sea-level change (gravitationally self-consistent, GRACE, Farrell)
• Surface mass balance (PDD, MUNGSM, d18O, components, GEMB)
• Basal melting (linear, quadratic, PICO, Beckmann-Goosse, ISMIP6)
• Inverse methods (control method, AD-based inversion for friction/rheology)
• Uncertainty quantification (Dakota integration, sampling)

Key difference from hydrological models: ISSM operates on unstructured triangular/prismatic finite-element meshes over ice sheet domains (Antarctica, Greenland, individual glaciers). It is not a gridded basin model. The primary workflow is MATLAB/Python scripted, and the C++ core handles the numerical solve via PETSc.

Installation

Source

ISSM v2026.1:    source/repo/
Repository:      github.com/ISSMteam/ISSM
License:         BSD 3-Clause
Platforms:       Linux, macOS, Windows (MSYS2)

Dependencies (external packages)

Required:

• C/C++ compiler (gcc/g++ or clang)
• Fortran compiler (gfortran)
• Autotools (autoconf, automake, libtool)
• PETSc (with bundled BLAS/LAPACK, MPICH, METIS, ParMETIS, MUMPS, ScaLAPACK)
• Triangle (mesh generation)
• M1QN3 (optimization, Fortran)

Optional:

• MATLAB (for MATLAB interface)
• Python 3 + NumPy (for Python interface)
• Dakota (uncertainty quantification)
• ADOLC/CoDiPack (automatic differentiation)
• GDAL/PROJ (geospatial data)
• GMT/GMSH (mesh generation, mapping)
• Boost (C++ utilities)
• NetCDF/HDF5 (data I/O)

Build Process

# 1. Install external packages (PETSc bundles most deps)
cd externalpackages/petsc
./install-3.22-linux64.sh 4    # 4 = number of CPUs
 
cd ../triangle
./install-linux64.sh
 
# 2. Source environment
source etc/environment.sh
 
# 3. Configure
./scripts/automakererun.sh
./configure \
  --prefix=${ISSM_DIR} \
  --with-petsc-dir=${ISSM_DIR}/externalpackages/petsc/install \
  --with-triangle-dir=${ISSM_DIR}/externalpackages/triangle/install \
  --with-mpi-include=${ISSM_DIR}/externalpackages/petsc/install/include \
  --with-mpi-libflags="-L${ISSM_DIR}/externalpackages/petsc/install/lib -lmpi -lmpicxx -lmpifort" \
  --with-blas-lapack-dir=${ISSM_DIR}/externalpackages/petsc/install
 
# 4. Build
make -j 8
make install

Produced Binaries

Python Dependencies

numpy, scipy, netCDF4 (for Python API)

Test Example

examples/SquareIceShelf/     # Simplest idealized test
  runme.m / runme.py         # Main script (8 lines)
  Square.par / Square.py     # Parameterization (31 lines)
  DomainOutline.exp          # Domain boundary (5 points)
  Front.exp                  # Ice front boundary

Pipeline (9 stages)

Stage Dependencies

Stage 0 → Stage 1 → Stage 2 → Stage 3 → Stage 4 (optional) → Stage 5 → Stage 6 → Stage 7 → Stage 8

All stages are sequential. Stage 4 (extrusion) is only needed for 3D simulations (HO, FS).

Tools Reference