Description

This example describes how to install and use EnsembleKalmanProcesses alongside the model-ensembler, using an idealised Pine Island example. This example is derived using code in the original library example for learning parameterisations of a sine wave (examples/SinusoidInterface), and is a modified version of the example in KalmanEnsembling. The current set up is for use on the BAS HPC with julia versions 1.10 and earlier.

Setup

First, clone this repository.

Then, inside it:

python -m venv venv
source venv/bin/activate
pip install --upgrade setuptools pip
pip install -r requirements.txt 

Idealised Pine Island example using Kalman Ensembling

This example using Kalman Ensembling to constrain several parameters: weertman_c_prefactor (basal sliding prefactor), glen_a_prefactor (ice viscosity prefactor), bump_amplitude (magnitude of the 1940s pycnocline displacement), melt_rate_prefactor (ice-shelf basal melt rate exponent prefactor), per_century_trend (per-century-trend in pycnocline height in metres). These parameters are taken from Bradley et al. 2025. The priors for these parameters are given in Priors.toml.

Key Files

generate_data.jl - creates the synthetic ‘truth’ data used as observations in this example.

initialize_EKP.jl - generates parameter values using Priors.toml, and sets up the EKP object which gets populated at each iteration.

ensemble.yaml - sets up the workflow. This defines the jobs, uses templates to insert parameter combinations into each driver script for each ensemble member, and defines how many iterations should be run.

run_computer_model.jl - runs WAVI for each ensemble member and iteration. Calls parameter_to_data_map() in WAVI_driver.jl.

WAVI_driver.jl - driver script that sets up the WAVI ice sheet model.

update_EKP.jl - performs the Ensemble Kalman Update.

run_EKP.sh - sets up julia packages and runs the EKP with the command model_ensemble -p -rt 30 -st 10 -ct 30 -v ensemble.yaml

To run:

Change the julia filepathways in ensemble.yaml, template/run_computer_model.sh.j2, and run_EKP.sh to your local installation. Then:

chmod +x *.sh
./run_EKP.sh

You will be prompted to enter the number of ensemble members, number of iterations, and the name of your job. Press enter to leave each as its default (10, 20, username).

Output structure

The output will be stored in ensemble/output/iteration_XXX/member_XXX.

Inside ensemble:

Project.toml – a configuration file that defines the dependencies and metadata.

Manifest.toml – automatically generated upon running the EKP and contains the exact versions of every package and their dependencies that were installed.

Inside output:

truth.jld2 – the observational data generated by generate_data.jl.

eki.jld2 - contains the Ensemble Kalman Process (EKP) object, which stores the current state of the ensemble including parameter values, observation data, and ensemble statistics (overwritten at each iteration).

iteration_XXX – containing member directories with output files.

Inside each member directory:

parameters.toml - the updated parameter ensemble from update_EKP.jl for that iteration, for use in the next iteration.

output.jld2 – the ensemble member output at the same time as the truth data, used in the Ensemble Kalman Update.

outfileXXXX.mat – output files at regular timesteps.

outfile.nc – all outfiles together in a netcdf.

To visualise the results, run plot_ensemble.py.

License

This is a derived example from the Julia library and thus the original attribution license is in LICENSE.example, with the workflow being additionally licensed using the Apache 2.0 license, contained under LICENSE.