A 1-d radiative-thermodynamic heat transfer model for glacier ice.
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, use a free one:
- 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 will run anIceModelsimulation for the KAN_M weather station, located on the Greenland ice sheet, for year 2016 on a 1-hr 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/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 take between one and a few minutes to run. Initial run times may be longer due to JIT compilation.
The model input and output directories default to the top-level folders input/ and output/ (note that the .gitignore in this repo ignores these folders).
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.
To set run-specific model options and parameters, open and edit the function icemodel/+icemodel/setopts.m. In your matlab terminal:
- Type
edit icemodel.setoptsand press enter. - Edit the options and resave the function.
- Run the model with the new options (see
demo.mfor an example of how to callicemodel.run.pointto run the model).
Example input files are in demo/inputs. These include the meteorological forcing data in inputs/met, inputs to the two-stream spectral model in inputs/spectral, and optional "user data" in inputs/userdata.
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 inputs/userdata directory contains alternative model forcings that can be "swapped out" with the standard model forcings to test hypotheses about processes and model sensitivity. For instance, users can prepare input forcing data generated from observations, climate model output, or satellite remote sensing, and place these files in userdata. Unlike the forcing files in inputs/met, these files do not need to contain the complete set of model forcings.
To swap out a variable in the input met file with a variable in a userdata file, set the userdata and uservars configuration parameters (see demo/demo.m). For example, setting userdata="modis" and uservars="albedo" would replace the albedo values in the input meteorological forcing file with modis albedo for the same time and location. This would require placing a file named <sitename>_modis_<year> (see Naming Conventions) in the userdata directory, containing a timetable named Data with a variable (column) named albedo.
- Install this repo and place it on your Matlab path
- Edit and run the following files
| Function Name | Description | How to Run |
|---|---|---|
icemodel.config |
Set global configuration settings. | 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. |
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 is:
met_SITENAME_FORCINGS_YYYY_TIMESTEP
For example:
met_kanm_kanm_2016_1hr.mat specifies a met (forcing) data file for site KAN-M with KAN-M forcings for year 2016 at a 1-hour timestep.
met_kanm_kanm_2016_15m.mat specifies a met (forcing) data file for site KAN-M with KAN-M forcings for year 2016 at a 15-minute timestep.
met_kanm_merra_2016_15m.mat specifies a met (forcing) data file for site KAN-M with MERRA-2 forcings for year 2016 at a 15-minute timestep.
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 is:
SITENAME_FORCINGS_YYYY
Note: at this time, only hourly userdata files are supported, therefore there is no TIMESTEP file part like the met file naming convention.
For example:
KANM_MERRA_2016.mat specifies a user data file with MERRA-2 climate model forcings for the KAN-M weather station location for year 2016.
Each userdata file must contain a timetable named Data with column names matching the met file column-naming conventions. See the example met file in demo/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.matICEMODEL_OUTPUT_PATH/SITENAME/SMBMODEL/YYYY/ice2_FORCINGS_forcings_USERDATA_USERVARS.matICEMODEL_OUTPUT_PATH/SITENAME/SMBMODEL/opts/opts_FORCINGS_forcings_USERDATA_USERVARS.mat
Here, 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.
Note that the ICEMODEL_OUTPUT_PATH/SITENAME/SMBMODEL/YYYY subfolders are generated automatically in the icemodel.setopts function if they do not exist.
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.mat
If 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.mat
Here, 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.
*Note that the main program icemodel/icemodel.m and core IceModel functions (UPPERCASE filenames in icemodel/), 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 namespace functions (e.g. icemodel/+icemodel), 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.