Official repository for the SAI Simulator, a new tool to explore the effects of stratospheric aerosol injection on the climate.

• Introduction
• Setup Options
• Option 1: Automated Setup (Recommended)
• Option 2: Manual Setup
  • Environment Setup
  • Data Download
  • Data Processing
  • Fit the Regression Models
  • Variability Calculation
  • Cache the Data
• License
• Citation

The SAI Simulator is a web-based tool that runs in your browser at simulator.reflective.org. If you would like to reproduce the steps to prepare the data presented in the simulator, you can follow the instructions below.

There are two ways to set up the SAI Simulator locally:

Both options require ~140GB of disk space for data storage.

The automated setup script guides you through the entire installation process interactively. It asks all configuration questions up front, then executes the setup steps.

./setup.sh

The script will:

1. Ask all configuration questions up front (environment type, data directories, which steps to run)
2. Set up your Python environment (Conda or venv)
3. Optionally compile and install ESMF (default version: release/8.9.0)
4. Download ~140GB of data from S3
5. Process the data and fit regression models
6. Cache the data for the simulator

After setup completes, see the Manual Setup section for usage instructions.

Use this option if you want full control over each step or need to troubleshoot specific parts of the setup.

We recommend using Python 3.11 or higher (all code is tested using Python 3.12.12).

Set up a new Conda environment and install required packages:

conda create -n sai-simulator python=3.12.12 -c conda-forge
conda activate sai-simulator
pip install -r requirements.txt

If you prefer to use venv instead of Conda, follow these steps:

python -m venv .venv
source .venv/bin/activate  # On Windows: venv\Scripts\activate
pip install --upgrade pip
pip install -r requirements.txt

The SAI Simulator requires the ESMF (Earth System Modeling Framework) library to be compiled from source.

Prerequisites:

• gfortran: brew install gcc
• Xcode Command Line Tools: xcode-select --install

Installation Steps:

1. Clone the ESMF repository:

   git clone https://github.com/esmf-org/esmf.git
   cd esmf

2. Checkout a release branch (e.g., release/8.9.0):

   git checkout release/8.9.0

3. Clean previous builds and set up the build environment:

   make distclean
   export ESMF_DIR=$(pwd)
   export ESMF_BOPT=O
   export ESMF_CXX=/usr/bin/clang++
   export ESMF_C=/usr/bin/clang
   export ESMF_F90=gfortran
   export ESMF_COMPILER=gfortranclang
   export ESMF_SHARED_LIB_BUILD=ON
   export ESMF_CXXLINKLIBS="-lc++"
   export ESMF_F90LINKLIBS="-lc++"
   export ESMF_COMM=mpiuni

4. Build ESMF (this takes 10-20 minutes):

   make

5. Verify the libraries exist in lib/libO/<os-system>/:

   • libesmf_fullylinked.dylib (or .so on Linux)
   • libesmf.dylib (or .so on Linux)
   • esmf.mk

6. Set the ESMFMKFILE environment variable and add it to your shell configuration:

   export ESMFMKFILE=$(find $ESMF_DIR/lib/libO -name "esmf.mk" | head -1)
   echo "export ESMFMKFILE=\"$ESMFMKFILE\"" >> ~/.zshrc  # or ~/.bashrc
   source ~/.zshrc  # or ~/.bashrc

7. Install ESMPy:

   cd src/addon/esmpy
   python -m pip install .

Download the necessary data from AWS S3 bucket (requires around 140GB of disk space):

1. Create a data repository:

   mkdir -p data/raw

2. Download the data (takes about 30 minutes to 2 hours based on your internet speed):

   aws s3 sync s3://reflective-simulator-bucket/v1.3.0/ ./data/raw/ --no-sign-request

3. Download the LENS NCAR data for minimum and maximum temperature (please note that the --overwrite flag is optional):

   sh scripts/run_download_CESM_LENS.sh TREFHTMX monthly data/raw 001 002 003 --overwrite
   sh scripts/run_download_CESM_LENS.sh TREFHTMN monthly data/raw 001 002 003 --overwrite

1. Process the daily data to create monthly values. You can process all the daily data (both tas and pr) using:

   sh scripts/process_all_daily.sh data/raw

   Or you can process the daily data for a specific variable (e.g. tas) using:

   python scripts/process_daily_gauss.py --var tas --data_dir data/raw

2. Process the monthly data to create annual values ready for model fitting. You can process all the monthly data using:

   sh scripts/process_all_monthly.sh data/raw data/processed

   Or you can process the monthly data for a specific variable using:

   python scripts/process_monthly_gauss.py  --var tas --data_dir data/raw --output_dir data/processed

3. Calculate model internal variability for sea ice by running the following command:

   python scripts/variability.py icefrac ./data/processed ./data/models

We fit linear regression models to (1) estimate a gridded map of each variable given a global temperature output by FaIR and (2) estimate a gridded delta of each variable given a global temperature delta. The models are trained using the GAUSS simulation data.

You can fit the regression models for all variables using:

sh scripts/fit_all.sh data/processed data/models

Or you can fit the regression models for a specific variable using:

python scripts/fit_map.py --var tas --data_dir data/processed --output_dir data/models
python scripts/fit_delta.py --var tas --data_dir data/processed --output_dir data/models

To calculate grid cell level and global model internal variability, we need to run the variability script.

python scripts/variability.py --var_name icefrac --data_dir data/processed data/models

The simulator caches all the data to be loaded more efficiently by the frontend. You can cache the data by running the following command:

python scripts/cache.py --data_dir data/processed --model_dir data/models --output_dir data/cache

This project is released under the Apache 2.0 License - see the LICENSE file for details.

If you use the SAI Simulator in your work, please cite the following:

Ali Akherati, Susanne Baur, Charlotte DeWald, Jake Dexheimer, Alistair Duffey, Jared Farley, Dakota Gruener, Jeremy Irvin, Emily Kuhn, Douglas MacMartin, John Orcutt, Kate Pellegrino, Daniele Visioni, Duncan Watson-Parris, Kion Yaghoobzadeh. (2026). SAI Simulator (Version 1.3.0) [Software]. Available at GitHub: https://github.com/Reflective-org/sai-simulator. Hosted at: https://simulator.reflective.org and https://planetparasol.ai.  DOI: https://doi.org/10.5281/zenodo.19099782