ise

ISE (Ice Sheet Emulator) package root. Provides end-to-end tools for training and running ice sheet emulators, centred on ISEFlow — a hybrid normalizing-flow + deep-ensemble model that produces sea level projections with full uncertainty quantification (epistemic and aleatoric) for the Antarctic Ice Sheet (AIS) and Greenland Ice Sheet (GrIS).

Subpackages

• ise.data
  • Submodules
  • ise.data.anomaly
  • ise.data.forcings
  • ise.data.grids
  • ise.data.inputs
  • ise.data.feature_engineer
  • ise.data.process
  • ise.data.dataclasses
  • ise.data.scaler
  • ise.data.utils
  • Module contents
• ise.models
  • Submodules
  • ise.models.iseflow
  • ise.models.deep_ensemble
  • ise.models.lstm
  • ise.models.normalizing_flow
  • ise.models.loss
  • ise.models.training
  • ise.models.pretrained
  • Module contents
• ise.models._experimental
  • Submodules
  • ise.models._experimental.gp
  • ise.models._experimental.pca
  • ise.models._experimental.scenario
  • ise.models._experimental.variational_lstm_emulator
  • Module contents
• ise.evaluation
  • Submodules
  • ise.evaluation.metrics
  • Module contents
• ise.utils
  • Submodules
  • ise.utils.functions
  • ise.utils.io
  • Module contents

Module contents

ISE — Ice Sheet Emulator package.

ISE provides end-to-end tools for training and running ice sheet emulators, with a focus on ISEFlow: a hybrid normalizing-flow + deep-ensemble model that produces sea level projections with full uncertainty quantification (epistemic and aleatoric) for the Antarctic Ice Sheet (AIS) and Greenland Ice Sheet (GrIS).

Quickstart

Install the package:

pip install ise-py

Load the pretrained AIS emulator and make a prediction:

from ise.models import ISEFlow_AIS
from ise.data.inputs import ISEFlowAISInputs

model = ISEFlow_AIS(version="v1.1.0")
inputs = ISEFlowAISInputs(...)
predictions, uncertainties = model.predict(inputs)

Package layout

• ise.data — forcing/grid loading, feature engineering, dataset classes

• ise.models — ISEFlow, DeepEnsemble, NormalizingFlow, LSTM, loss functions

• ise.evaluation — point, probabilistic, and distribution metrics

• ise.utils — data helpers, tensor utilities

For questions contact Peter Van Katwyk at pvankatwyk@gmail.com.

class ise.ISEFlow(deep_ensemble, normalizing_flow)

Bases: Module

ISEFlow is a hybrid ice sheet emulator that combines a deep ensemble model and a normalizing flow model.

This class provides methods to train, predict, save, and load hybrid models for ice sheet emulation. It integrates a deep ensemble to capture epistemic uncertainties and a normalizing flow to model aleatoric uncertainties.

device

The computing device (‘cuda’ if available, else ‘cpu’).

Type:

str

deep_ensemble

The deep ensemble model for epistemic uncertainty.

Type:

DeepEnsemble

normalizing_flow

The normalizing flow model for aleatoric uncertainty.

Type:

NormalizingFlow

trained

Flag indicating whether the model has been trained.

Type:

bool

scaler_path

Path to the scaler used for output transformation.

Type:

str or None

fit(X, y, nf_epochs, de_epochs, batch_size=64, X_val=None, y_val=None, save_checkpoints=True, checkpoint_path='checkpoint_ensemble', early_stopping=True, sequence_length=5, patience=10, verbose=True)

Trains the hybrid emulator using the provided data.

This method trains the normalizing flow model first, then uses its latent representations to train the deep ensemble model.

Parameters:

• X (array-like) – Input feature matrix.

• y (array-like) – Target values.

• nf_epochs (int) – Number of training epochs for the normalizing flow.

• de_epochs (int) – Number of training epochs for the deep ensemble.

• batch_size (int, optional) – Batch size for training. Defaults to 64.

• X_val (array-like, optional) – Validation feature matrix. Defaults to None.

• y_val (array-like, optional) – Validation target values. Defaults to None.

• save_checkpoints (bool, optional) – Whether to save training checkpoints. Defaults to True.

• checkpoint_path (str, optional) – Path prefix for saving model checkpoints. Defaults to ‘checkpoint_ensemble’.

• early_stopping (bool, optional) – Whether to use early stopping. Defaults to True.

• sequence_length (int, optional) – Sequence length for recurrent architectures. Defaults to 5.

• patience (int, optional) – Number of epochs with no improvement before stopping. Defaults to 10.

• verbose (bool, optional) – Whether to print training progress. Defaults to True.

Raises:

Warning – If the model has already been trained.

forward(x)

Run a forward pass through the hybrid emulator.

Parameters:

x (array-like) – Input feature matrix with shape (N, num_features).

Returns:

(prediction, uncertainties) where:

• prediction (numpy.ndarray): Mean prediction across ensemble members.

• uncertainties (dict): Keys 'total', 'epistemic', 'aleatoric' with numpy arrays giving per-row uncertainty in scaled (model) units.

Return type:

tuple

Warns:

UserWarning – If the model has not been trained.

static load(model_dir=None, deep_ensemble_path=None, normalizing_flow_path=None)

Load a trained ISEFlow from saved deep ensemble and normalizing flow checkpoints.

Provide either model_dir (which expects deep_ensemble.pth and normalizing_flow.pth files inside it) or both deep_ensemble_path and normalizing_flow_path explicitly.

Parameters:

• model_dir (str, optional) – Directory containing the saved sub-model files.

• deep_ensemble_path (str, optional) – Explicit path to the saved deep ensemble.

• normalizing_flow_path (str, optional) – Explicit path to the saved normalizing flow.

Returns:

The loaded model, with trained=True.

Return type:

ISEFlow

predict(x, output_scaler=True, smoothing_window=0)

Predict SLE projections and uncertainties, applying inverse scaling and optional smoothing.

Smoothing is applied to the final unscaled predictions and uncertainties so the physical SLE curve is what gets smoothed (rather than scaled values).

Parameters:

• x (array-like) – Input feature matrix with shape (N, num_features).

• output_scaler (bool or str, optional) – If True (default), loads the scaler bundled with the pretrained model. If False, returns un-rescaled predictions. If a string, loads the sklearn scaler at that path and uses it to inverse-transform the output.

• smoothing_window (int, optional) – Width of a centered moving-average smoother applied to the unscaled predictions and uncertainties. 0 (default) disables smoothing.

Returns:

(unscaled_predictions, uncertainties) where:

• unscaled_predictions (numpy.ndarray): Predictions in mm SLE.

• uncertainties (dict): Keys 'total', 'epistemic', 'aleatoric' with numpy arrays in mm SLE.

Return type:

tuple

Warns:

UserWarning – If no scaler is available; predictions and uncertainties are then returned in the model’s scaled output space rather than mm SLE.

save(save_dir, input_features=None, output_scaler_path=None)

Saves the trained model and related components to a specified directory.

Parameters:

• save_dir (str) – Directory where the model should be saved.

• input_features (list, optional) – List of input feature names. Defaults to None.

• output_scaler_path (str, optional) – Path to the output scaler. Defaults to None.

Raises:

• ValueError – If the model has not been trained.

• ValueError – If save_dir is a file instead of a directory.

• ValueError – If input_features is not a list.

class ise.ISEFlow_AIS(version='v1.1.0')

Bases: ISEFlow

Pretrained ISEFlow emulator for the Antarctic Ice Sheet (AIS).

Loads pretrained weights for AIS (18 sectors, 8 km resolution) from HuggingFace Hub and exposes predict(inputs) where inputs is an ISEFlowAISInputs instance.

Note

version refers to the ISEFlow model weights version, not the ise-py package version. See ise.models.pretrained.ISEFLOW_LATEST_MODEL_VERSION for the current default.

Supported model versions:

• v1.0.0: includes mrro_anomaly as a forcing variable.

• v1.1.0 (default): mrro_anomaly removed; improved GrIS+AIS joint training.

Parameters:

version (str, optional) – ISEFlow model weights version. One of 'v1.0.0' or 'v1.1.0'. Defaults to the latest: 'v1.1.0'.

Raises:

NotImplementedError – If an unsupported version string is provided.

predict(inputs: ISEFlowAISInputs, smoothing_window: int = 0)

Predicts AIS sea level contribution using the pretrained ISEFlow_AIS model.

Internally calls process() to scale, add lag variables, and one-hot encode the inputs before running the hybrid forward pass.

Parameters:

• inputs (ISEFlowAISInputs) – Validated input dataclass containing climate forcings and ISM configuration for a single sector.

• smoothing_window (int, optional) – If > 0, applies a uniform moving-average smoother of this width to the output time series. Defaults to 0 (no smoothing).

Returns:

A tuple containing:

• predictions (numpy.ndarray, shape (86, 1)): Unscaled sea level equivalent (SLE) projections in mm for years 2015-2100.

• uncertainties (dict): Dictionary with keys:

  • 'total': total uncertainty (epistemic + aleatoric).

  • 'epistemic': uncertainty from ensemble disagreement.

  • 'aleatoric': uncertainty from normalizing-flow sampling.

Return type:

tuple

process(inputs: ISEFlowAISInputs)

Preprocess ISEFlowAISInputs into the feature matrix expected by the model.

Applies input scaling (using the version-specific scaler_X.pkl), adds 5-step lag variables, one-hot encodes ISM configuration columns, and pads any missing one-hot columns with False.

Parameters:

inputs (ISEFlowAISInputs) – Validated input dataclass for a single AIS sector.

Returns:

Feature matrix aligned to the column order expected by the pretrained model weights for the current version.

Return type:

pandas.DataFrame

Raises:

ValueError – If mrro_anomaly is None when using v1.0.0.

test(X_test)

Tests the model on a test dataset.

Parameters:

X_test (array-like) – Test feature matrix.

Returns:

A tuple containing:

• unscaled_predictions (numpy.ndarray): Model predictions in the original scale.

• uncertainties (dict): Dictionary with keys:

  • ’total’ (numpy.ndarray): Total uncertainty.

  • ’epistemic’ (numpy.ndarray): Epistemic uncertainty.

  • ’aleatoric’ (numpy.ndarray): Aleatoric uncertainty.

Return type:

tuple

class ise.ISEFlow_GrIS(version='v1.1.0')

Bases: ISEFlow

Pretrained ISEFlow emulator for the Greenland Ice Sheet (GrIS).

Loads pretrained weights for GrIS (6 drainage basins, 5 km resolution) from HuggingFace Hub and exposes predict(inputs) where inputs is an ISEFlowGrISInputs instance.

Note

version refers to the ISEFlow model weights version, not the ise-py package version. See ise.models.pretrained.ISEFLOW_LATEST_MODEL_VERSION for the current default.

Supported model versions:

• v1.0.0: initial GrIS release.

• v1.1.0 (default): improved AIS+GrIS joint training.

Parameters:

version (str, optional) – ISEFlow model weights version. One of 'v1.0.0' or 'v1.1.0'. Defaults to the latest: 'v1.1.0'.

Raises:

NotImplementedError – If an unsupported version string is provided.

predict(inputs: ISEFlowGrISInputs, smoothing_window: int = 0)

Predicts GrIS sea level contribution using the pretrained ISEFlow_GrIS model.

Internally calls process() to scale, add lag variables, and one-hot encode the inputs before running the hybrid forward pass.

Parameters:

• inputs (ISEFlowGrISInputs) – Validated input dataclass containing climate forcings and ISM configuration for a single GrIS drainage basin.

• smoothing_window (int, optional) – If > 0, applies a uniform moving-average smoother of this width to the output time series. Defaults to 0 (no smoothing).

Returns:

A tuple containing:

• predictions (numpy.ndarray, shape (86, 1)): Unscaled sea level equivalent (SLE) projections in mm for years 2015-2100.

• uncertainties (dict): Dictionary with keys:

  • 'total': total uncertainty (epistemic + aleatoric).

  • 'epistemic': uncertainty from ensemble disagreement.

  • 'aleatoric': uncertainty from normalizing-flow sampling.

Return type:

tuple

process(inputs: ISEFlowGrISInputs)

Preprocess ISEFlowGrISInputs into the feature matrix expected by the model.

Applies input scaling (using the version-specific scaler_X.pkl), adds 5-step lag variables, one-hot encodes ISM configuration columns, and pads any missing one-hot columns with False.

Parameters:

inputs (ISEFlowGrISInputs) – Validated input dataclass for a single GrIS basin.

Returns:

Feature matrix aligned to the column order expected by the pretrained model weights for the current version.

Return type:

pandas.DataFrame

test(X_test)

Tests the model on a test dataset.

Parameters:

X_test (array-like) – Test feature matrix.

Returns:

A tuple containing:

• unscaled_predictions (numpy.ndarray): Model predictions in the original scale.

• uncertainties (dict): Dictionary with keys:

  • ’total’ (numpy.ndarray): Total uncertainty.

  • ’epistemic’ (numpy.ndarray): Epistemic uncertainty.

  • ’aleatoric’ (numpy.ndarray): Aleatoric uncertainty.

Return type:

tuple