ISE Documentation ================= .. image:: https://readthedocs.org/projects/ise/badge/?version=latest :target: https://ise.readthedocs.io/en/latest/ :alt: Documentation Status .. image:: https://badge.fury.io/py/ise-py.svg :target: https://pypi.org/project/ise-py/ :alt: PyPI version .. image:: https://img.shields.io/badge/python-3.11+-blue.svg :target: https://python.org :alt: Python 3.11+ .. image:: https://img.shields.io/badge/License-MIT-yellow.svg :target: https://github.com/Brown-SciML/ise/blob/master/LICENSE.md :alt: License: MIT .. image:: https://github.com/Brown-SciML/ise/actions/workflows/ci.yml/badge.svg :target: https://github.com/Brown-SciML/ise/actions/workflows/ci.yml :alt: CI **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: 1. **NormalizingFlow** — autoregressive masked affine flow trained via maximum likelihood on ISMIP6 outputs. Captures **aleatoric** (data) uncertainty via posterior sampling. 2. **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: .. code-block:: shell pip install ise-py For development (editable install): .. code-block:: shell git clone https://github.com/Brown-SciML/ise.git cd ise pip install -e ".[dev]" Quickstart — pretrained ISEFlow-AIS ===================================== .. code-block:: python 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 :doc:`quickstart` page. Package layout ============== .. code-block:: text 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: 1. **Fork the repository** on GitHub. 2. **Create a new branch** for your feature or bugfix. 3. **Submit a pull request** (PR) for review. Run tests before submitting: .. code-block:: shell 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. .. toctree:: :maxdepth: 3 :caption: Contents: quickstart model_versions docs/source/ise