ismip7_forcing

The landice/ismip7_forcing test group processes (i.e., remaps and renames) the atmospheric and ocean thermal forcing data of the Ice Sheet Model Intercomparison for CMIP7 (ISMIP7) protocol. The processed data is used to force MALI in its simulations under the ISMIP7 experimental protocol. The test group supports both the Antarctic Ice Sheet (AIS) and the Greenland Ice Sheet (GrIS), controlled by a single ice_sheet config option.

The test group includes three test cases: atmosphere, ocean_thermal, and fracture. Each begins with a build_mapping_file step that runs ESMF with a separate resource allocation.

  • The atmosphere test case has six steps: build_mapping_file, process_smb, process_temperature, process_smb_gradient, process_temperature_gradient, and process_runoff.

  • The ocean_thermal test case has three steps: build_mapping_file, process_thermal_forcing, and build_3d_thermal_forcing. process_thermal_forcing produces, for AIS, 3D thermal forcing (with 30 ocean depth layers) and, for GrIS, 2D (depth-averaged) thermal forcing. It can also process the observational ocean thermal forcing climatology (Zhou et al.) for AIS, controlled by the process_ocean_climatology config option. build_3d_thermal_forcing optionally converts the GrIS 2D forcing into a 3D field (GrIS only, controlled by process_ocean_thermal_3d).

  • The fracture test case has four steps: build_mapping_file, process_excess_melt (Path A), process_lake_properties (Path B), and process_shelf_collapse (Path C). It processes the ISMIP7 surface-melt-driven ice shelf collapse forcing (AIS only).

(For more details on the steps of each test case, see atmosphere, ocean_thermal, and fracture.)

Usage

To use this test group, users need to:

  1. Provide a MALI mesh file onto which the source data will be remapped.

  2. Set the ice_sheet config option to either ais or gis.

  3. Set base_path_ismip7 to the root of the native ISMIP7 archive, which contains the AIS and GIS directories.

  4. Run the atmosphere test case for each model and scenario combination.

  5. Run the ocean_thermal test case for each model and scenario combination.

  6. Run the fracture test case (AIS only) for each model and scenario combination to process the surface-melt-driven ice shelf collapse pathways (excess melt, lake properties, and the ice shelf collapse mask).

The mapping step can be run first on a large allocation, followed by the processing steps on a single node. Newly built weights are saved in {output_base_path}/mapping_files. Set mapping_files_path to that directory in later runs to reuse weights for the same source grid, MALI mesh, and remapping method.

Example user config files are provided in the source tree for local testing:

  • compass/landice/tests/ismip7_forcing/ismip7_forcing_test.cfg (AIS-focused example)

  • compass/landice/tests/ismip7_forcing/ismip7_forcing_test_gis.cfg (GrIS-focused example)

These files contain machine-specific absolute paths and are intended as templates, not portable defaults. Copy one and edit paths and options for your environment before using it with compass setup ... -f USER.cfg.

The AIS example enables both ocean processing modes and uses a 2015-2300 processing window for both atmosphere and ocean thermal scenario forcing. The GrIS example enables scenario ocean processing only and uses 1980-2015.

For the GrIS OCX (reanalysis) scenario, use the dedicated example config compass/landice/tests/ismip7_forcing/ismip7_forcing_ocx_gis.cfg. OCX has no distinct ESM model: it uses RACMO2.3p2-ERA for the atmosphere and EN4 for the ocean, both selected automatically when scenario = OCX. The [ismip7] model option is ignored for OCX (set it to None), so a single config file processes both the atmosphere and ocean_thermal test cases, just like the ESM scenarios.

Output Layout

Processed forcing is written under output_base_path in a layout that the ismip7_run test group can ingest directly:

{output_base_path}/{group}/atmosphere/{mesh}_SMB_{source}_{scenario}_{years}.nc
{output_base_path}/{group}/atmosphere/{mesh}_temperature_{source}_{scenario}_{years}.nc
{output_base_path}/{group}/atmosphere/{mesh}_runoff_...  (and the two gradients)
{output_base_path}/{group}/shelf_collapse/{mesh}_ice_shelf_collapse_mask_*.nc
{output_base_path}/{group}/excess_melt/{mesh}_excess_melt_*.nc
{output_base_path}/{group}/lake_properties/{mesh}_lake_properties_*.nc
{output_base_path}/{group}/ocean_thermal_forcing/{mesh}_2dThermalForcing_{source}_{scenario}_{years}.nc  (GrIS)
{output_base_path}/{group}/ocean_thermal_forcing/{mesh}_3dThermalForcing_{source}_{scenario}_{years}.nc  (AIS; optional GrIS 3-D)
{output_base_path}/{group}/ocean_thermal_forcing/{mesh}_meltParams_OCX.nc  (GrIS 3-D calibration)

The group directory is {model}_{scenario} for ESM scenarios and OCX for GrIS OCX. AIS OCX writes one group per selected ocean product, OCX_{choice}, and links the shared atmosphere files into each group. To feed ismip7_run, point forcing_basepath at output_base_path for ESM scenarios; point ocx_forcing_path at {output_base_path}/OCX for GrIS OCX or {output_base_path}/OCX_{choice} for AIS OCX.

Process only one year range into a given group directory: the run setup expects exactly one file per forcing field there.

Input Data

base_path_ismip7 is the unmodified archive root. The resolver selects files from these native layouts:

{root}/{AIS|GIS}/{model}/{scenario}/{product}-{resolution}/{variable}/{version}/*.nc
{root}/AIS/{model}/{scenario}/ocean/tf/{version}/*.nc
{root}/GIS/{model}/{scenario}/ocean-{resolution}/tf/{version}/*.nc
{root}/AIS/{model}/{scenario}/fracture/{version}/*.nc
{root}/AIS/OCX/RACMO2.3p2-ERA/SDBN1-{resolution}/{variable}/{version}/*.nc
{root}/GIS/OCX/RACMO2.3p2-ERA/SDBN1-{resolution}/{variable}/{version}/*.nc
{root}/AIS/OCX/ocean/{choice}/{version}/*.nc
{root}/GIS/OCX/EN4/ocean-{resolution}/tf/{version}/*.nc

The atmosphere product and atmosphere and GrIS ocean resolution are configurable. auto selects the primary product for the requested model and the finest available resolution. Set an explicit value to use another archive product or grid.

Versions default to latest and are compared numerically, including dotted versions such as v2.1. Atmosphere versions are resolved separately for each variable because the archive does not version all fields in lockstep. An explicit section-wide version may be set for reproducibility; an option such as acabf_version = v2 overrides it for one atmosphere variable. The newest directory must contain matching files, so an incomplete transfer is reported rather than silently replaced with an older version.

The observational climatology remains configured separately with base_path_climatology. Its version also defaults to latest below the tf directory.

config options

The ismip7_forcing test group uses five config sections. The default values are:

# config options for ismip7 forcing data
[ismip7]

# Ice sheet: ais (Antarctic) or gis (Greenland)
ice_sheet = NotAvailable

# Root of the native archive (the directory containing AIS/ and GIS/)
base_path_ismip7 = NotAvailable

# Base path to the MALI mesh
base_path_mali = NotAvailable

# Base path to which output forcing files are saved
output_base_path = NotAvailable

# Name of climate model (e.g., CESM2-WACCM, MRI-ESM2-0)
model = NotAvailable

# Scenario (e.g., historical, ssp126, ssp370, ssp585)
scenario = NotAvailable

# Name of the MALI mesh (used in output file naming)
mali_mesh_name = NotAvailable

# MALI mesh file name
mali_mesh_file = NotAvailable

# Number of MPI tasks for ESMF_RegridWeightGen
esmf_ntasks = 128

# Optional directory containing compatible mapping files from another run
mapping_files_path = NotAvailable

# Whether to process time-varying ocean thermal forcing (ESM scenario data)
process_ocean_thermal = true

# Whether to process observational ocean thermal forcing climatology
process_ocean_climatology = true

# Whether to build regional 3-D Greenland ocean thermal forcing from the
# 2-D forcing (GrIS only; Antarctica already produces 3-D forcing)
process_ocean_thermal_3d = false

# config options for ismip7 atmosphere forcing
[ismip7_atmosphere]

# Product and source resolution
product = auto
resolution = auto

# Resolve separately for each variable; explicit versions are also valid
version = latest

# Remapping method: bilinear, neareststod, conserve
method_remap = conserve

# Start year for processing
start_year = 1850

# End year for processing
end_year = 2014

# config options for ismip7 ocean thermal forcing
[ismip7_ocean_thermal]

# GrIS source resolution and dataset version
resolution = auto
version = latest

# Remapping method: bilinear, neareststod, conserve
method_remap = bilinear

# Start year for processing
start_year = 1850

# End year for processing
end_year = 2014

# config options for ismip7 ocean thermal forcing climatology
[ismip7_ocean_climatology]

# Remapping method: bilinear, neareststod, conserve
method_remap = bilinear

# Dataset version
version = latest

# Base path to observational climatology data
base_path_climatology = /path/to/ISMIP7/forcing/AIS/obs/zhou_annual_06_nov

# config options for building 3-D Greenland ocean thermal forcing
[ismip7_ocean_thermal_3d]

# Path to the JSON config with the 3-D-specific parameters (EN4 directory,
# region-mask file, source-region GeoJSON, calibration, vertical grid).
# User must supply when process_ocean_thermal_3d is true.
config_file = NotAvailable

# config options for ismip7 fracture (Path C, ice shelf collapse) forcing
[ismip7_fracture]

# Remapping method for each pathway. Set a method to None to skip
# processing that pathway's file.

# Remapping method for the ice shelf collapse mask (Path C).
# neareststod preserves the 0/1 mask values
method_remap_shelf_collapse = neareststod

# Remapping method for the excess meltwater field (Path A), a flux
method_remap_excess_melt = conserve

# Remapping method for the supraglacial lake properties (Path B)
method_remap_lake_properties = bilinear

# Version subdirectory of the fracture forcing data
version = latest

# Start year for processing
start_year = 1850

# End year for processing
end_year = 2014

All NotAvailable options must be overridden in a user config file passed at setup time (e.g., compass setup ... -f my_ismip7.cfg).

The boolean options process_ocean_thermal and process_ocean_climatology control which processing paths are executed when the ocean_thermal test case is run. Both default to true. Set one to false in your user config to skip that processing path.

atmosphere

The landice/ismip7_forcing/atmosphere test case processes the ISMIP7 atmosphere forcing fields and remaps them from the native polar stereographic grid to the MALI unstructured mesh.

Steps:

  • build_mapping_file: Builds and caches weights for the selected atmosphere product and resolution. All five processing steps share these weights.

  • process_smb: Remaps the surface mass balance (acabf) field. The output variable is sfcMassBal.

  • process_temperature: Remaps the surface temperature (ts) field, clipped to a maximum of 273.15 K. The output variable is surfaceAirTemperature.

  • process_smb_gradient: Remaps the SMB lapse rate (dacabfdz) field. The output variable is sfcMassBalLapseRate.

  • process_temperature_gradient: Remaps the temperature lapse rate (dtsdz) field. The output variable is surfaceAirTemperatureLapseRate.

  • process_runoff: Remaps the ice sheet runoff (mrro) field. The output variable is ismip6Runoff.

ocean_thermal

The landice/ismip7_forcing/ocean_thermal test case processes the ISMIP7 ocean thermal forcing (tf) and remaps it from the native polar stereographic grid to the MALI unstructured mesh.

The build_mapping_file step builds and caches mappings for each enabled source grid. Scenario and climatology mappings are distinct when their source grids differ. The process_thermal_forcing step consumes those mappings.

The step supports two processing modes, controlled by boolean config options in the [ismip7] section:

  • Scenario (time-varying) data (process_ocean_thermal = true): Processes ESM-driven thermal forcing for a given model/scenario combination.

  • Observational climatology (process_ocean_climatology = true): Processes the static Zhou et al. observational thermal forcing climatology (AIS only). This is a time-invariant 3D field referenced to 1995-2024.

Both modes can be enabled simultaneously.

For AIS scenario data, thermal forcing is 3D with 30 vertical ocean layers. The input files span decades (e.g., 1850-1859). The output variable is ismip6shelfMelt_3dThermalForcing with dimension nISMIP6OceanLayers. Associated depth coordinate variables ismip6shelfMelt_zOcean and ismip6shelfMelt_zBndsOcean are also produced.

For AIS climatology data, the output is the same 3D thermal forcing field but without a Time dimension, producing a single static file.

For GrIS, thermal forcing is 2D (depth-averaged), with monthly temporal resolution and yearly input files. The output variable is ismip6_2dThermalForcing.

build_3d_thermal_forcing (GrIS 3-D)

The optional build_3d_thermal_forcing step (GrIS only, gated by process_ocean_thermal_3d = true) converts the GrIS 2D thermal forcing into a configurable-level 3D field for MALI’s nonlocal (Jourdain et al. 2020) melt scheme (default 20 levels; configurable via ocean_vertical_grid.number_of_levels in the JSON). It auto-chains from the 2D forcing the process_thermal_forcing step just wrote, builds seven regional vertical profiles from monthly EN4 objective analyses, anchors each cell’s profile to the effective seafloor to match the 2D forcing, and calibrates one ismip6shelfMelt_deltaT per region while holding ismip6shelfMelt_gamma0 fixed.

The 3-D-specific parameters (EN4 directory, region-mask file, source-region GeoJSON, calibration targets, vertical grid, physical constants) are supplied through a JSON config file referenced by the [ismip7_ocean_thermal_3d] config_file option; the mesh, 2D forcing, output, and diagnostics paths are injected automatically. The output supplements (does not replace) the 2D forcing and uses the variables ismip6shelfMelt_3dThermalForcing, ismip6shelfMelt_deltaT, ismip6shelfMelt_gamma0, ismip6shelfMelt_zOcean, and ismip6shelfMelt_basin, matching the AIS 3D convention.

fracture

The landice/ismip7_forcing/fracture test case processes the ISMIP7 surface-melt-driven ice shelf collapse forcing (AIS only). It implements the three ISMIP7 pathways as separate steps, each remapping annual fields from the native 8km polar stereographic grid onto the MALI unstructured mesh.

All three source files are discovered from AIS/{model}/{scenario}/fracture/{version}/ below base_path_ismip7.

Each pathway is run independently and can be skipped by setting its remapping-method config option to None in the [ismip7_fracture] section (for example, method_remap_excess_melt = None skips Path A). This is useful when only some of the pathway source files are available.

The build_mapping_file step uses a fracture file with native x/y coordinates as the common grid template and creates one mapping file per unique enabled remapping method.

  • process_excess_melt (Path A): Remaps the excess meltwater field (melt + rain after firn air content depletion), matching excess_melt_*.nc. The output variable is ismip7ExcessMelt (converted from mm w.e. yr-1 to SI units of kg m-2 s-1) and is written to {output_base_path}/{model}_{scenario}/excess_melt/. Conservative remapping is used by default since this is a flux. This source file has no x/y coordinate variables and its array is flipped along the y axis relative to the other fracture files, so the step reconstructs the source grid (borrowing x/y from a sibling fracture file and flipping the data to match) before remapping.

  • process_lake_properties (Path B): Remaps the supraglacial lake mean depth and area fraction from the Grau et al. (2025) parameterization, matching lake_properties_*.nc. The output variables are ismip7LakeDepth (m) and ismip7LakeAreaFraction (unitless), written to {output_base_path}/{model}_{scenario}/lake_properties/. Bilinear remapping is used by default.

  • process_shelf_collapse (Path C): Remaps the annual ice shelf collapse mask, matching ice_shelf_collapse_mask_*.nc. An ice shelf grid cell is flagged as collapsed (mask value 1) when excess meltwater, computed after firn air content depletion, exceeds 72.5 mm/yr for 10 consecutive years; otherwise the mask value is 0. The mask is applied on floating areas only, similar to ISMIP6, and ice shelves collapse on January 1st of each year. The remapping uses neareststod by default so that the 0/1 mask values are preserved, and the remapped mask is rounded to 0/1. The output variable is calvingMask with an accompanying xtime variable, and the result is written to {output_base_path}/{model}_{scenario}/shelf_collapse/.

All three pathways produce continuous fields (Paths A and B) or a discrete mask (Path C) with an accompanying xtime variable. The output variable names for Paths A and B (ismip7ExcessMelt, ismip7LakeDepth, ismip7LakeAreaFraction) are descriptive placeholders and may need to be aligned with the MALI Registry once the corresponding model input fields are defined.