A 1-d radiative-thermodynamic heat transfer model for glacier ice.
- IceModel
IceModel is based on models of glacier ice and snowpack described in Liston et al (1999) and Jordan (1991) (SNTHERM). State variables are ice temperature and liquid water content, from which various hydrologic and thermodynamic quantities are computed, including the flux of meltwater runoff.
Following Liston et al (1999), IceModel implements the two-stream radiative transfer model described in Schlatter (1972), updated with spectral detail following Brandt and Warren (1993). The surface energy balance largely follows Liston et al (1999), including the turbulent flux parameterization based on Monin-Obukhov similarity theory (Monin & Obukhov, 1954). IceModel follows both Liston et al (1999) and SNTHERM for subsurface thermodynamics, including representations of solar radiative heating, conductive heat transfer, and vapor diffusion, but implements an enthalpy-conserving numerical phase change scheme described in Clark et al. (2021) and Swaminathan and Voller (1993).
A technical description is available here.
Thanks for your interest. To get started, here's what we recommend:
- Check the system requirements and installation guide.
- If you do not have a MATLAB license, you can run this software using a free MATLAB Online account:
- The main program is
icemodel/icemodel.m. Open the function to get a sense for the model structure. - Open and run Example 1 in
demo/demo.m. This runs the KAN_M weather-station case on the Greenland ice sheet for 2016 using a 15-minute timestep. - Inspect the demo plot created by the call to
icemodel.plot.enbal. The simulated energy fluxes should closely track the weather station values. - Set
saveflag=trueand re-run Example 1. Notice how thedemo/data/outputdirectory is created, and the model output is saved there. - Set
backupflag=trueand re-run Example 1. Notice how the files are backed-up. By default, saveflag and backupflag are both false.
The examples in demo.m run IceModel in its "SkinModel" surface energy balance configuration. Run-time will depend on your computer, but should take less than one minute. An IceModel configuration (which includes a full subsurface energy balance) should also take less than one minute to run. Initial run times may be longer due to JIT compilation.
The model data directories default to the top-level folders under data/ (the .gitignore in this repo ignores data/input/, data/eval/, and data/output/).
To specify custom input and output directories, use the configuration function icemodel/+icemodel/config.m. In your matlab terminal:
- Type
edit icemodel.configand press enter. - Read the detailed documentation to understand the model input and output directory structure, and how to set them programmatically.
demo.m selects icemodel.config(casename="demo"), which scopes the run to the small tracked demo/data tree. The test and verification cases select their data roots.
Run-specific model options and parameters are set by icemodel/+icemodel/setopts.m, which returns the opts struct the model runs on. In your matlab terminal:
- Type
edit icemodel.setoptsand press enter. - Read the documentation to see the available options and their default values.
To change an option for one run, pass it to icemodel.run.point in the overrides struct rather than editing setopts:
[ice1, ice2, met, opts] = icemodel.run.point( ...
"sitename", "kanm", ...
"simyears", 2016, ...
"smbmodel", "icemodel", ...
"overrides", struct('dt', 900, 'solver', 3));icemodel.resetopts applies each override by field name and clears the derived options that depend on it, then icemodel.configureRun rebuilds them inside the model. An option name that setopts does not define is an error. The model returns the resolved opts as its fourth output, so you can see exactly which options the run used. Edit setopts to change a default for every run.
The minimal example inputs are in demo/data/input: the KAN-M 2016 15-minute forcing and MERRA-2 userdata file under input/met, plus the two-stream tables under input/spectral. The MODIS example uses the MODIS data column included in the demo forcing file to run the model with MODIS albedo rather than the KAN-M weather station albedo.
The spectral directory contains values for the absorption coefficient of pure ice from Warren et al. 2008, in-situ absorption coefficients for glacier ice from Cooper et al. 2021, a downwelling solar spectrum for the Arctic atmosphere generated with ATRAN (Lord, 1991), and a library of mie-scattering coefficients as described in Cooper et al. 2021.
The model supports an input/userdata directory containing alternative model forcings that can be swapped into the standard forcing to test hypotheses about processes and model sensitivity. Unlike files in input/met, userdata files do not need to contain every model forcing.
To swap a variable, set the userdata and uservars configuration parameters (see demo/demo.m). A "swappable" alternative forcing variable source can be included in the primary forcing file as an additional column, as the demo MODIS column is, or supplied by a matching file in input/met/<source> or input/userdata/<source>.
- Install this repo and place it on your Matlab path
- Open and run
demo/demo.m - For advanced use, edit and run the following files:
| Function Name | Description | How to Run |
|---|---|---|
icemodel.config |
Set global configuration (model input and output paths). | Type edit icemodel.config then press enter. Set the environment variables programmatically as needed. |
icemodel.setopts |
Set run-specific model configuration. | Type edit icemodel.setopts then press enter. Edit the model options and save the function, or override them per run (see runtime configuration). |
icemodel.run.point |
Run the model at a point. | See the example in demo.m, and the function arguments in icemodel.run.point for additional configuration. |
demo.m |
Script to run and evaluate the model output. | Place this repo on your matlab path, edit and run the script. |
- File names are in lowercase for operating system compatibility.
- Non-standard characters in filename parts (e.g., "-", "&") are replaced with blanks. For example, sitename "KAN-M" becomes "kanm".
The met (forcing data) file naming convention has two forms:
- per year:
met_SITENAME_FORCINGS_YYYY_TIMESTEP - per time-window:
met_SITENAME_FORCINGS_YYYYMMDD_YYYYMMDD_TIMESTEP(preferred when a run setsopts.startdate/opts.enddate)
Here FORCINGS is the forcing-source label (a versioned climate product such as mar3.11 / merra2 / racmo2.3p3, a station such as kanm, the generic AWS source promice, or the ESM-SnowMIP family esm_snowmip). Met file names therefore follow met_<site>_<source> across all forcing product families. A legacy per-station convention is also supported, which sets FORCINGS == SITENAME (e.g. met_kanm_kanm_...) whereas the recommended convention is met_kanm_promice_.... Here, the kanm weather station is part of the promice forcing product. The label names the product rather than its readiness: promice is the native station record, which has gaps in most station-years, so a runnable PROMICE forcing is usually the gap-filled product promice_filled (see icemodel.setopts).
Examples:
met_kanm_kanm_2016_15m.matspecifies a met (forcing) data file for site KAN-M with KAN-M forcings for year 2016 at a 15-minute timestep.met_kanm_merra2_20160101_20161231_15m.matspecifies a time-window stamped met file for site KAN-M with MERRA-2 forcings throughout 2016 at a 15-minute timestep.met_cdp_esm_snowmip_19940801_20140731_1hr.matspecifies an ESM-SnowMIP time-window stamped met file for sitecdpspanning 1994-2014 at a 1-hour timestep.
Met files live under input/met/, staged into per-source subfolders input/met/<FORCINGS>/ (recommended), or staged directly in input/met/ (legacy convention). At runtime, the model resolves input/met/<FORCINGS>/ first and falls back to a flat input/met/ path, so both layouts work.
The recommended model timestep is 15-minute. Each met file must contain a timetable object named met with one column for each forcing variable. See the example met file.
The "userdata" file naming convention has two forms:
- per year:
SITENAME_SOURCE_YYYY - per time-window:
SITENAME_SOURCE_YYYYMMDD_YYYYMMDD(preferred when a run setsopts.startdate/opts.enddate)
Examples:
kanm_merra2_2016.matspecifies a user data file with MERRA-2 climate model forcings for the KAN-M weather station location for year 2016 on a 1-hr timestep.kanm_modis_2016.matspecifies a user data file with MODIS satellite albedo values for the KAN-M weather station location for year 2016 on a 1-hr timestep.
As with met files, userdata files are staged into per-source subfolders input/userdata/<SOURCE>/ and the model resolves that subfolder first at runtime, with a flat input/userdata/ fallback.
Each userdata file must contain a timetable named Data with column names matching the met file column-naming conventions. Userdata files are staged at a 1-hr timestep by default, but a staging function can keep the native cadence of its source, as the MODIS albedo stager does; at runtime, variables are linearly interpolated to the configured model timestep (e.g., 15-min). See the example met file in demo/data/input/.
IceModel produces two outputs: ice1 and ice2, representing 1-dimensional and 2-dimensional data, respectively, with dimensions time and depth. The ice1 data are saved in a timetable object and ice2 are saved in a struct object. An IceModel simulation with opts.saveflag set true will save these two objects as well as the opts struct according to the following convention:
ICEMODEL_OUTPUT_PATH/SITENAME/SMBMODEL/YYYY/ice1_FORCINGS_forcings_USERDATA_USERVARS.mat
ICEMODEL_OUTPUT_PATH/SITENAME/SMBMODEL/YYYY/ice2_FORCINGS_forcings_USERDATA_USERVARS.mat
ICEMODEL_OUTPUT_PATH/SITENAME/SMBMODEL/opts/opts_FORCINGS_forcings_USERDATA_USERVARS.mat
ICEMODEL_OUTPUT_PATH/SITENAME/SMBMODEL/restart/restart_FORCINGS_forcings_USERDATA_USERVARS_YYYY.matHere, ICEMODEL_OUTPUT_PATH is an environment variable set by the icemodel.config function, the lowercase "forcings" is a string literal used to join the FORCINGS and USERDATA string variables, and SITENAME, SMBMODEL, FORCINGS, USERDATA, and USERVARS are parameters passed to the icemodel.setopts function (either directly or indirectly via the helper function icemodel.run.point). One YYYY folder is created for each year in the SIMYEARS parameter passed to icemodel.setopts.
The ICEMODEL_OUTPUT_PATH/SITENAME/SMBMODEL/YYYY subfolders are created automatically when the model run starts if they do not exist. If opts.saverestart is enabled, a sibling restart/ folder is also created under the same run output directory and stores one restart file per saved year.
Example: An IceModel simulation for the KAN-M weather station location for years 2015:2016 using MERRA forcings, with userdata='modis' and uservars='albedo' will produce the following output files:
ICEMODEL_OUTPUT_PATH/kanm/icemodel/2015/ice1_merra_forcings_modis_albedo.mat
ICEMODEL_OUTPUT_PATH/kanm/icemodel/2015/ice2_merra_forcings_modis_albedo.mat
ICEMODEL_OUTPUT_PATH/kanm/icemodel/2016/ice1_merra_forcings_modis_albedo.mat
ICEMODEL_OUTPUT_PATH/kanm/icemodel/2016/ice2_merra_forcings_modis_albedo.mat
ICEMODEL_OUTPUT_PATH/kanm/icemodel/opts/opts_merra_forcings_modis_albedo.matIf userdata and uservars are not supplied to icemodel.setopts or are supplied as empty arrays [], or empty chars '' (they are optional arguments but must be supplied as empty if subsequent arguments saveflag and/or backupflag are supplied), the filenames would be:
ICEMODEL_OUTPUT_PATH/kanm/icemodel/2015/ice1_merra_forcings_merra_albedo.mat
ICEMODEL_OUTPUT_PATH/kanm/icemodel/2015/ice2_merra_forcings_merra_albedo.matHere, the userdata parameter takes on the value of the forcings parameter ('merra'), whereas the uservars parameter takes the value 'albedo', which is the default value set in icemodel.setopts. This reflects the focus of IceModel on studying the sensitivity of SMB models to ice albedo.
Brandt R E and Warren S G 1993 Solar-heating rates and temperature profiles in Antarctic snow and ice Journal of Glaciology 39 99–110
Clark M P, Zolfaghari R, Green K R, Trim S, Knoben W J M, Bennett A, Nijssen B, Ireson A and Spiteri R J 2021 The Numerical Implementation of Land Models: Problem Formulation and Laugh Tests Journal of Hydrometeorology 22 1627–48 Online
Cooper M G, Smith L C, Rennermalm Å K, Tedesco M, Muthyala R, Leidman S Z, Moustafa S E and Fayne J V 2021 Spectral attenuation coefficients from measurements of light transmission in bare ice on the Greenland Ice Sheet The Cryosphere 15 1931–53, Online
Jordan R 1991 A One-Dimensional Temperature Model For a Snowpack (Hanover, NH: Cold Regions Research and Engineering Laboratory) Online
Liston G E, Bruland O, Elvehøy H and Sand K 1999 Below-surface ice melt on the coastal Antarctic ice sheet Journal of Glaciology 45 273–85, Online
Lord S D 1992 A new software tool for computing Earth’s atmospheric transmission of near-and far-infrared radiation vol 103957 (Ames Research Center)
Monin A S and Obukhov A M 1954 Basic laws of turbulent mixing in the surface layer of the atmosphere Contrib. Geophys. Inst. Acad. Sci. USSR 151 e187
Schlatter T W 1972 The Local Surface Energy Balance and Subsurface Temperature Regime in Antarctica J. Appl. Meteor. 11 1048–62 Online
Swaminathan C R and Voller V R 1993 ON THE ENTHALPY METHOD International Journal of Numerical Methods for Heat & Fluid Flow 3 233–44
Warren S G and Brandt R E 2008 Optical constants of ice from the ultraviolet to the microwave: A revised compilation J. Geophys. Res. 113 D14220, Online
- Requires MATLAB® version >=9.2* (R2017a).
- R2016b is a hard limit on compatibility: IceModel forcing files are currently stored as
timetableobjects which were introduced (along withstring) in R2016b.
- R2016b is a hard limit on compatibility: IceModel forcing files are currently stored as
- Developed and tested on MacOS Sonoma (Intel silicon), using MATLAB R2022b.
- Runs in MATLAB Online (a linux-based system), tested on R2022b.
- Runs on Windows 10, tested on R2017a.
*The main program icemodel/icemodel.m and the core +icemodel namespace functions (that is, functions called in the icemodel.m call stack) are written in a minimalist matlab style: all functions are compatible with code generation, all numerical methods employ custom hand-written solvers, and there are no toolbox dependencies or modern matlab conveniences such as arguments input parsers.
Exceptions to this style include non-core-physics namespace functions (e.g. icemodel/+icemodel/+helpers), which by convention are helper functions not required by the numerical model. The demo.m script uses a modern matlab approach including name=value syntax (requires >=R2021a). The arguments parser used in icemodel.run.point requires >=R2019b. For users running pre-R2019b, see demo/demo_pre_R2019.m.
If you encounter incompatibilities, please open an issue.
Download this repo and place it on the matlab path.
In a terminal:
git clone https://github.com/mgcooper/icemodel.gitIn your matlab terminal:
cd('/path/to/this/repo')
setup()Installation should only take a few seconds. If you encounter any issues, please open an issue.
The examples in demo/demo.m only need the tracked inputs in demo/data. The test suite and the verification workflows read larger data trees that are not tracked in this repo. Those trees are published as data archives attached to each release, and the provisioning function installs them:
icemodel.verification.setup.fetchFixtures()Called without arguments, it installs the two mandatory capabilities for the version in CITATION.cff: formal-core, which installs to test/data, and verification-showcase. Pass download=false to verify an installation without network access. See icemodel/+icemodel/+verification/README_FIXTURES.md for the capability table and the offline and pre-publication options.
Running the model and the snow-verification workflow needs nothing beyond this repo. A few auxiliary workflows (building gridded-climate forcings, and the permafrost-zone site classification used by icemodel.verification) call out to external dev-repo toolboxes that are kept out of this repo:
| Repo | Used by | Path added |
|---|---|---|
exactremap |
conservative (area-weighted) polygon remap in icemodel.forcing.helpers.remapPolygon |
exactremap/toolbox |
activelayer |
Obu (UiO PEX) permafrost-zone reader activelayer.readobuzones used by site classification |
activelayer/toolbox |
matfunclib |
shared helpers activelayer depends on (parseFileName, dealout, ...) |
matfunclib |
These are wired by the single central function icemodel.dependencies, which the test suite bootstrap calls automatically. It resolves each repo root in this order, and it changes nothing when a dependency is already on the path or absent:
- A dependency-specific environment variable:
ICEMODEL_EXACTREMAP,ICEMODEL_ACTIVELAYER,ICEMODEL_MATFUNCLIB. - A shared projects-root variable
ICEMODEL_PROJECTS_ROOT, joined with the repo name (e.g.$ICEMODEL_PROJECTS_ROOT/exactremap). - The sibling
projects/layout (the parent folder of this repo).
To use a non-default location, clone the repos and either set the env vars or clone them next to this repo. To add them to the path yourself:
icemodel.dependencies() % no-op for anything already on the path
icemodel.dependencies(require=true) % error if any dependency is missingmatfunclib must be on the path for activelayer to load.
If you find a bug, have a question, or want to contribute, feel free to open an issue or start a discussion.
If you find this software useful, please consider citing the software release in CITATION.cff (click the link in the "About" section along the right sidebar of this repo).