ise.models.ISEFlow

ise.models.ISEFlow.ISEFlow

class ise.models.ISEFlow.ISEFlow.ISEFlow(deep_ensemble, normalizing_flow)[source]

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)[source]

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, smooth_projection=False)[source]

Performs a forward pass through the hybrid emulator.

Parameters:

  • x (array-like) - Input data.

  • smooth_projection (bool, optional) - Whether to apply smoothing to projections. Defaults to False.

Returns:

A tuple containing:

  • prediction (numpy.ndarray): Model predictions.

  • uncertainties (dict): Dictionary with keys:

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

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

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

Return type:

tuple

Raises:

Warning - If the model has not been trained.

static load(model_dir=None, deep_ensemble_path=None, normalizing_flow_path=None)[source]

Loads a trained ISEFlow model from specified paths.

Parameters:

  • model_dir (str, optional) - Directory containing the saved model. Defaults to None.

  • deep_ensemble_path (str, optional) - Path to the saved deep ensemble model. Defaults to None.

  • normalizing_flow_path (str, optional) - Path to the saved normalizing flow model. Defaults to None.

Returns:

The loaded ISEFlow model.

Return type:

ISEFlow

Raises:

NotImplementedError - If an unsupported version is specified.

predict(x, output_scaler=True, smooth_projection=False)[source]

Makes predictions using the trained hybrid emulator.

Parameters:

  • x (array-like) - Input data.

  • output_scaler (bool or str, optional) - Path to the output scaler or whether to apply scaling. Defaults to True.

  • smooth_projection (bool, optional) - Whether to apply smoothing. Defaults to False.

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

Raises:

Warning - If no scaler path is provided.

save(save_dir, input_features=None, output_scaler_path=None)[source]

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.models.ISEFlow.ISEFlow.ISEFlow_AIS[source]

Bases: ISEFlow

ISEFlow_AIS is a specialized version of ISEFlow for the Antarctic Ice Sheet (AIS).

This subclass initializes the deep ensemble and normalizing flow models specifically for AIS and provides a loading method with pre-trained model paths.

static load(version='v1.0.0', model_dir=None, deep_ensemble_path=None, normalizing_flow_path=None)[source]

Loads a trained ISEFlow_AIS model.

Parameters:

  • version (str, optional) - Model version. Defaults to “v1.0.0”.

  • model_dir (str, optional) - Directory of the saved model. Defaults to None.

  • deep_ensemble_path (str, optional) - Path to deep ensemble model. Defaults to None.

  • normalizing_flow_path (str, optional) - Path to normalizing flow model. Defaults to None.

Returns:

The loaded model.

Return type:

ISEFlow_AIS

Raises:

NotImplementedError - If an unsupported version is specified.

predict(year: array, pr_anomaly: array, evspsbl_anomaly: array, mrro_anomaly: array, smb_anomaly: array, ts_anomaly: array, ocean_thermal_forcing: array, ocean_salinity: array, ocean_temperature: array, initial_year: int, numerics: str, stress_balance: str, resolution: int, init_method: str, melt_in_floating_cells: str, icefront_migration: str, ocean_forcing_type: str, ocean_sensitivity: str, ice_shelf_fracture: bool, open_melt_type: str = None, standard_melt_type: str = None)[source]

Predicts ice sheet evolution using the trained ISEFlow_AIS model.

Parameters:

method) ((Same as process)

Returns:

A tuple containing:

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

  • uncertainties (dict): Dictionary containing different uncertainty components.

Return type:

tuple

process(year: array, pr_anomaly: array, evspsbl_anomaly: array, mrro_anomaly: array, smb_anomaly: array, ts_anomaly: array, ocean_thermal_forcing: array, ocean_salinity: array, ocean_temperature: array, initial_year: int, numerics: str, stress_balance: str, resolution: int, init_method: str, melt_in_floating_cells: str, icefront_migration: str, ocean_forcing_type: str, ocean_sensitivity: str, ice_shelf_fracture: bool, open_melt_type: str = None, standard_melt_type: str = None)[source]

Processes input data for prediction by applying necessary transformations and encoding.

Parameters:

  • year (np.array) - Years of the input data.

  • pr_anomaly (np.array) - Precipitation anomaly data.

  • evspsbl_anomaly (np.array) - Evaporation anomaly data.

  • mrro_anomaly (np.array) - Runoff anomaly data.

  • smb_anomaly (np.array) - Surface mass balance anomaly.

  • ts_anomaly (np.array) - Surface temperature anomaly.

  • ocean_thermal_forcing (np.array) - Ocean thermal forcing.

  • ocean_salinity (np.array) - Ocean salinity.

  • ocean_temperature (np.array) - Ocean temperature.

  • initial_year (int) - Initial year for modeling.

  • numerics (str) - Numerical scheme used.

  • stress_balance (str) - Stress balance model.

  • resolution (int) - Resolution of the model.

  • init_method (str) - Initialization method.

  • melt_in_floating_cells (str) - Melt treatment method.

  • icefront_migration (str) - Ice front migration scheme.

  • ocean_forcing_type (str) - Type of ocean forcing applied.

  • ocean_sensitivity (str) - Ocean sensitivity setting.

  • ice_shelf_fracture (bool) - Whether ice shelf fracture is considered.

  • open_melt_type (str, optional) - Type of open melt model. Defaults to None.

  • standard_melt_type (str, optional) - Type of standard melt model. Defaults to None.

Returns:

Processed input data ready for prediction.

Return type:

pd.DataFrame

Raises:

ValueError - If any input arguments are invalid.

class ise.models.ISEFlow.ISEFlow.ISEFlow_GrIS[source]

Bases: ISEFlow

ISEFlow_GrIS is a specialized version of ISEFlow for the Greenland Ice Sheet (GrIS).

This subclass initializes the deep ensemble and normalizing flow models specifically for GrIS and provides a loading method with pre-trained model paths.

static load(version='v1.0.0', model_dir=None, deep_ensemble_path=None, normalizing_flow_path=None)[source]

Loads a trained ISEFlow_GrIS model.

(Same arguments and return type as ISEFlow_AIS.load.)

ise.models.ISEFlow.de

class ise.models.ISEFlow.de.ISEFlow_AIS_DE[source]

Bases: DeepEnsemble

ISEFlow Deep ensemble model for Antarctic Ice Sheet (AIS) emulation.

This class implements an ensemble of Long Short-Term Memory (LSTM) networks to predict ice sheet dynamics using deep learning. It extends the DeepEnsemble class and combines multiple LSTM models to enhance predictive performance.

input_size

The number of input features, Defaults to 99.

Type:

int

output_size

The number of output features, Defaults to 1.

Type:

int

iseflow_ais_ensemble

A list of LSTM models with different architectures and loss functions.

Type:

list

Inherits from:

DeepEnsemble: A base class for deep ensemble models.

class ise.models.ISEFlow.de.ISEFlow_GrIS_DE[source]

Bases: DeepEnsemble

ISEFlow Deep ensemble model for Greenland Ice Sheet (GrIS) emulation.

This class constructs an ensemble of LSTM models to predict ice sheet behavior for the Greenland Ice Sheet (GrIS). It extends the DeepEnsemble framework and integrates multiple LSTM-based predictors to improve accuracy.

input_size

The number of input features (90).

Type:

int

output_size

The number of output features (1).

Type:

int

iseflow_gris_ensemble

A list of LSTM models with varying architectures and loss functions.

Type:

list

Inherits from:

DeepEnsemble: A base class for deep ensemble models.

ise.models.ISEFlow.nf

class ise.models.ISEFlow.nf.ISEFlow_AIS_NF[source]

Bases: NormalizingFlow

ISEFlow_AIS_NF is a specialized normalizing flow model for the Antarctic Ice Sheet (AIS).

This class extends the NormalizingFlow class, configuring it with AIS-specific input sizes and transformations.

class ise.models.ISEFlow.nf.ISEFlow_GrIS_NF[source]

Bases: NormalizingFlow

ISEFlow_GrIS_NF is a specialized normalizing flow model for the Greenland Ice Sheet (GrIS).

This class extends the NormalizingFlow class, configuring it with GrIS-specific input sizes and transformations.