Imported from lzwei196/KISS---Knowledge-Infrastructure-for-Scientific-Simulation (models/ISSM/SKILL.md). Install upstream with npx skills add lzwei196/KISS---Knowledge-Infrastructure-for-Scientific-Simulation --skill ISSM. Copyright stays with the author.

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 — 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>.

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.

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: 4 tools | 5 skill documents | 20 diagnostic triplets | ~2,000 lines of validated Python Validation status: synthetic_only — only the SquareIceShelf/SquareSheet NightlyRun benchmarks have been executed (_work/ISSM/issm_run_test{101,201,301}.py, 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. Today the KI's outputs/ and _work/ISSM/ contain no real-glacier mesh, geometry, friction, or velocity data.

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

Total: 4 tools, ~1,100 lines of validated Python code.

Model Object (md) Structure

The ISSM model is represented by a model class with ~60 sub-objects:

Mesh & Domain

Geometry

Materials

Friction

Initialization

Boundary Conditions

Flow Equations

Solution Types

Input Formats

.exp (Argus Contour Format)

Domain boundaries and contours. ASCII format:

## Name:domainoutline
## Icon:0
# Points Count  Value
5 1.
# X pos Y pos
0 0
1000000 0
1000000 1000000
0 1000000
0 0

Units: Meters (projected coordinates, typically polar stereographic) Read by: expread() in MATLAB/Python

NetCDF (.nc)

External datasets (SeaRISE, BedMachine, etc.) with gridded fields:

• x1, y1 — grid coordinates (m)
• usrf — surface elevation (m)
• topg — bedrock topography (m)
• thkmask — grounded (1) / floating (-1) mask
• surfvelx, surfvely — surface velocity (m/yr)
• bheatflx_fox — geothermal heat flux (W/m^2)

.arch (Archive Format)

ISSM's custom binary format for storing pre-computed mesh/field data. Read by: archread() in MATLAB/Python

.par / .py (Parameter Files)

MATLAB or Python scripts executed with md in scope. These load data, interpolate onto mesh, and set all model fields.

Output Description (dag.yaml; template section 6)

Source of truth: dag.yaml. This section restates the dag so an agent reading only SKILL.md can identify the observable outputs and the headline variable. If this section ever disagrees with dag.yaml, the dag wins.

Headline output: IceVolume / GroundedArea / TotalSmb

IceVolume / GroundedArea / TotalSmb — Integrated transient diagnostics: total ice volume, grounded area, total surface mass balance per timestep. (m^3 / m^2 / m^3 ice eq)

The rank-1 output is transient and integrated: it is not a point snowpack SWE quantity, and it must not be validated against non-glacier station snowpack data.

Output Format

Results stored in md.results.<SolutionType>:

Stress Balance Results

Transient Results

Array of solutions per timestep:

md.results.TransientSolution[i].Vel    # velocity at timestep i
md.results.TransientSolution[i].Thickness  # thickness at timestep i

Export Options

• MATLAB .mat files (native)
• NetCDF via export_netCDF(md, 'output.nc')
• ParaView VTU format
• Binary ISSM format

Unit Table (template section 8)

Exact I/O shapes live in docs/format_spec.yaml; this table summarizes the units that matter when preparing ISSM inputs and interpreting dag outputs. The dag is the authority for output units, and ISSM documentation/examples are the authority for model object fields.

Unit Trap Table

CRITICAL: These unit mismatches cause silent failures. Each has a diagnostic triplet.

Critical Domain Knowledge

1. Velocity in m/yr, NOT m/s (dt_001)

ISSM uses meters per year for all velocity quantities. Satellite-derived velocities (e.g., MEaSUREs) are often in m/s or m/day. Off by ~3.15e7 if m/s is used directly. The ice will appear to not move at all.

2. Temperature in Kelvin, NOT Celsius (dt_002)

ISSM uses Kelvin for temperature fields. Climate reanalysis products typically provide °C. If you set md.initialization.temperature in °C, the ice will appear absurdly cold (e.g., -263°C becomes 10 K), and the rheology will be completely wrong.

3. Coordinates must be in meters (projected) (dt_004)

ISSM requires projected coordinates (e.g., polar stereographic) in meters. Geographic coordinates (lat/lon in degrees) will produce a mesh ~111,000x too small, and all physics will be wrong. Use EPSG:3031 for Antarctica, EPSG:3413 for Greenland.

4. Friction coefficient must be 0 on floating ice (dt_005)

Floating ice has no basal friction. If md.friction.coefficient is non-zero where md.mask.ocean_levelset < 0, the solver will apply basal drag to floating ice, producing unrealistically slow ice shelf velocities.

5. Glen's flow law: B vs A convention (dt_006)

ISSM uses the B (viscosity) convention: σ = 2 η ε̇ where η = B^n / (2 ε̇^(n-1)). Many publications use the A (fluidity) convention: ε̇ = A σ^n. Conversion: B = A^(-1/n). Using A directly as B produces velocities that are orders of magnitude wrong.

6. Thickness consistency: surface = base + thickness (dt_003)

ISSM enforces surface = base + thickness. If these are inconsistent (e.g., loaded from different datasets at different resolutions), the model may crash or produce non-physical results. Always compute one from the other two.

7. Mask levelset convention (dt_011)

• md.mask.ice_levelset < 0 → ice present
• md.mask.ice_levelset > 0 → no ice
• md.mask.ocean_levelset < 0 → floating (ocean below)
• md.mask.ocean_levelset > 0 → grounded (bedrock below)

These are SIGNED DISTANCE FUNCTIONS. Positive = outside, negative = inside. Confusing the sign convention produces inverted ice coverage.

8. Boundary conditions use NaN for free nodes (dt_012)

In ISSM, prescribed boundary conditions (spcvx, spcvy, spctemperature) use NaN to indicate a free (unconstrained) node. If you use 0 instead of NaN, the node is constrained to zero velocity/temperature, creating artificial ice divides or frozen boundaries.

9. The paterson() function converts T(K) → B(Pa s^1/n) (dt_006)

rheology_B = paterson(temperature_in_kelvin) is the standard way to set ice viscosity. Passing temperature in °C instead of K produces wrong rheology values. Always verify temperature is in Kelvin before calling paterson().

Skill Knowledge

Diagnostic Triplets

20 triplets covering 5 failure domains. See diagnostics/triplets.yaml for full details.

Silent error count: 13/20 (65%) — extremely high due to the model's tolerance of physically unreasonable inputs.

Validated Results (template section 11)

Current validation status: synthetic_only. The KI has executed only the SquareIceShelf/SquareSheet NightlyRun benchmarks in _work/ISSM/issm_run_test{101,201,301}.py; the Square.exp domain is a 5-point square, not a real glacier. Real-site validation is not done.

Before claiming a real-site result, fetch BedMachine geometry and MEaSUREs surface velocity for a glaciated target such as Pine Island Glacier, Thwaites, or Jakobshavn, then use tools/convert_geometry_to_issm.py to build a real md. The current outputs/ and _work/ISSM/ contents contain no real-glacier mesh, geometry, friction, or velocity data.

Convention Bars from docs/validation_convention.yaml

These bars are the KI's sourced validation convention. The convention wins over remembered thresholds. Null convention bands are written as no cited threshold; they are not pass/fail guesses.

No convention bar was provided in the extracted KI facts for the rank-1 output IceVolume / GroundedArea / TotalSmb; do not assign a validation verdict for that headline output unless docs/validation_convention.yaml supplies a cited threshold.

Validation Data Replacement Tracking

Quick Start (Python)

from model import *
from triangle import triangle
from setmask import setmask
from parameterize import parameterize
from setflowequation import setflowequation
from solve import solve
from generic import generic
from socket import gethostname

# Step 1: Create model and mesh
md = triangle(model(), 'DomainOutline.exp', 100000)  # 100 km resolution

# Step 2: Set mask (all floating for ice shelf)
md = setmask(md, 'all', '')

# Step 3: Parameterize
md = parameterize(md, 'Square.py')

# Step 4: Set flow equation
md = setflowequation(md, 'SSA', 'all')

# Step 5: Configure solver
md.cluster = generic('name', gethostname(), 'np', 2)

# Step 6: Solve
md = solve(md, 'Stressbalance')

# Step 7: Access results
print(f"Max velocity: {max(md.results.StressbalanceSolution.Vel)} m/yr")

Data Requirements

File Structure

ki/
  SKILL.md                            # This file (agent entry point)
  tools/
    convert_forcing_to_issm.py        # External forcing → ISSM input arrays
    convert_geometry_to_issm.py       # Bed/surface data → ISSM geometry
    run_issm.py                       # Execute ISSM Python simulation
    parse_issm_output.py              # Parse results to CSV/JSON
  docs/
    s1_mesh_generation.md             # Mesh creation and refinement
    s2_mask_definition.md             # Ice/ocean mask setup
    s3_parameterization.md            # Model parameterization
    s5_flow_equations.md              # Physics and solver config
    s7_execution.md                   # Running and post-processing
  diagnostics/
    triplets.yaml                     # 20 diagnostic triplets