ISE Documentation

ISE (Ice Sheet Emulator) is a Python package for training and running machine learning emulators of ice sheet models, with a focus on ISEFlow — a hybrid normalizing-flow + deep-ensemble neural network that produces sea level projections with full epistemic and aleatoric uncertainty quantification for the Antarctic Ice Sheet (AIS) and Greenland Ice Sheet (GrIS).

Supported ice sheets

AIS (Antarctic Ice Sheet): 18 sectors, 8 km standard resolution
GrIS (Greenland Ice Sheet): 6 drainage basins, 5 km standard resolution

Projection period: 2015–2100 (86 annual timesteps).

About ISEFlow

ISEFlow combines two sub-models trained in sequence:

NormalizingFlow — autoregressive masked affine flow trained via maximum likelihood on ISMIP6 outputs. Captures aleatoric (data) uncertainty via posterior sampling.
DeepEnsemble — ensemble of LSTM networks trained on the original features concatenated with NormalizingFlow latent representations. Captures epistemic (model) uncertainty as disagreement across members.

Total uncertainty = epistemic + aleatoric.

This codebase has been used in peer-reviewed research, including:

“A Variational LSTM Emulator of Sea Level Contribution From the Antarctic Ice Sheet”
“ISEFlow: A Flow-Based Neural Network Emulator for Improved Sea Level Projections and Uncertainty Quantification”
“Emulator-expanded projections reveal structure in Antarctic sea level uncertainty” (in review)

Manuscript-specific code is archived on Zenodo — see Manuscript code archives below for DOIs.

Installation

Install from PyPI:

pip install ise-py

For development (editable install):

git clone https://github.com/Brown-SciML/ise.git
cd ise
pip install -e ".[dev]"

Quickstart — pretrained ISEFlow-AIS

import numpy as np
from ise.models import ISEFlow_AIS
from ise.data.inputs import ISEFlowAISInputs

# Build the input dataclass for a single sector (sector 1)
year = np.arange(2015, 2101)          # 86 years

inputs = ISEFlowAISInputs(
    year=year,
    sector=np.ones(86, dtype=int),    # AIS sector 1 of 18
    pr_anomaly=np.zeros(86),
    evspsbl_anomaly=np.zeros(86),
    smb_anomaly=np.zeros(86),
    ts_anomaly=np.zeros(86),
    ocean_thermal_forcing=np.zeros(86),
    ocean_salinity=np.zeros(86),
    ocean_temperature=np.zeros(86),
    # ISM configuration — use model_configs shortcut or set individually
    model_configs="AWI_PISM1",
    ice_shelf_fracture=False,
    ocean_sensitivity="medium",
    ocean_forcing_type="standard",
    standard_melt_type="local",
)

# Load pretrained model (v1.1.0) and run inference
model = ISEFlow_AIS(version="v1.1.0")
predictions, uncertainties = model.predict(inputs)

print(predictions.shape)          # (86, 1)  — SLE in mm, 2015-2100
print(uncertainties["epistemic"]) # epistemic uncertainty per timestep
print(uncertainties["aleatoric"]) # aleatoric uncertainty per timestep
print(uncertainties["total"])     # total (epistemic + aleatoric)

For more examples including GrIS inference and training from scratch, see the Quickstart page.

Package layout

ise/
├── data/
│   ├── anomaly.py           AnomalyConverter: raw forcings → ISMIP6 anomalies
│   ├── forcings.py          ForcingFile: load/process climate NetCDF data
│   ├── grids.py             GridFile: sector boundary definitions
│   ├── inputs.py            ISEFlowAISInputs, ISEFlowGrISInputs
│   ├── feature_engineer.py  FeatureEngineer: split, scale, lag, outliers
│   ├── process.py           ProjectionProcessor, DatasetMerger, sector utils
│   ├── dataclasses.py       EmulatorDataset, PyTorchDataset, TSDataset
│   ├── scaler.py            PyTorch StandardScaler, RobustScaler, LogScaler
│   └── utils.py             convert_and_subset_times()
├── models/
│   ├── iseflow.py           ISEFlow, ISEFlow_AIS, ISEFlow_GrIS
│   ├── deep_ensemble.py     DeepEnsemble: ensemble of LSTM models
│   ├── lstm.py              LSTM: single LSTM network
│   ├── normalizing_flow.py  NormalizingFlow: autoregressive masked affine flow
│   ├── loss.py              WeightedGridLoss, WeightedMSELoss, and variants
│   ├── training.py          CheckpointSaver, EarlyStoppingCheckpointer
│   ├── pretrained/          Pretrained weight paths + expected variable lists
│   └── _experimental/       GP, PCA, ScenarioPredictor, VariationalLSTMEmulator
├── evaluation/
│   └── metrics.py           Point, probabilistic, and distribution metrics
└── utils/
    ├── functions.py         get_X_y, get_data, to_tensor, unscale_output, …
    └── io.py                check_type() runtime type validation

Contributing

We welcome contributions! To get started:

Fork the repository on GitHub.
Create a new branch for your feature or bugfix.
Submit a pull request (PR) for review.

Run tests before submitting:

pytest tests/

Manuscript code archives

The current ise-py package on PyPI is the actively maintained, versioned successor to the manuscript-specific codebases. Frozen snapshots of the code used in each publication are archived on Zenodo at the DOIs below:

“A Variational LSTM Emulator of Sea Level Contribution From the Antarctic Ice Sheet” — Peter Van Katwyk, Baylor Fox-Kemper, Helene Seroussi, Sophie Nowicki, Karianne Bergen. DOI: 10.5281/zenodo.10416633
“ISEFlow: A Flow-Based Neural Network Emulator for Improved Sea Level Projections and Uncertainty Quantification” — Peter Van Katwyk, Baylor Fox-Kemper, Sophie Nowicki, Helene Seroussi, Karianne Bergen. DOI: 10.5281/zenodo.14908114
“Emulator-expanded projections reveal structure in Antarctic sea level uncertainty” (in review) — Peter Van Katwyk, Baylor Fox-Kemper, Sophie Nowicki, Helene Seroussi, Karianne Bergen. Data & code DOI: 10.5281/zenodo.19355381

For new work, install the maintained package (pip install ise-py); use the Zenodo archives when you need to reproduce results from a specific paper.

Contact & Support

This repository is maintained by Peter Van Katwyk, Ph.D. student at Brown University.

Email: pvankatwyk@gmail.com
GitHub Issues: Report a bug

If you use ISE in research, please consider citing our work. See CITATION.md for details.