Topography Tasks

The e3sm/init/topo tasks create shared topography products and derived MPAS inputs that are reused by mesh-generation and E3SM initial-condition workflows.

Supported cubed-sphere products are:

  • ne3000

  • ne120

Supported latitude-longitude products are:

  • 1.00000_degree

  • 0.25000_degree

  • 0.12500_degree

  • 0.06250_degree

  • 0.03125_degree

Latitude-longitude product names follow the naming convention used by format_lat_lon_resolution_name(), which formats the resolution with 5 decimal places and appends _degree. For example, 0.125 becomes 0.12500_degree and 0.03125 becomes 0.03125_degree.

The standalone combine tasks listed below always regenerate the combined topography from scratch — they are not affected by the automatic caching that applies to downstream tasks. Other tasks that depend on a shared combine step (such as remap or ocean hydrography tasks) will automatically use cached outputs when they are available, without needing to opt in explicitly.

Standalone tasks are available to create each combined topography product:

  • e3sm/init/topo/combine_bedmap3_gebco2023/cubed_sphere/ne3000/task

  • e3sm/init/topo/combine_bedmap3_gebco2023/cubed_sphere/ne120/task

  • e3sm/init/topo/combine_bedmap3_gebco2023/lat_lon/1.00000_degree/task

  • e3sm/init/topo/combine_bedmap3_gebco2023/lat_lon/0.25000_degree/task

  • e3sm/init/topo/combine_bedmap3_gebco2023/lat_lon/0.12500_degree/task

  • e3sm/init/topo/combine_bedmap3_gebco2023/lat_lon/0.06250_degree/task

  • e3sm/init/topo/combine_bedmap3_gebco2023/lat_lon/0.03125_degree/task

The remap and cull tasks reuse these shared products when generating inputs for MPAS base meshes.

Remap and cull tasks are available for both simple (quasi-uniform and icosahedral) base meshes and for named unified meshes (see Unified base-mesh tasks). For a unified mesh named u.oi30.lr10, the task paths are:

  • e3sm/init/u.oi30.lr10/topo/remap

  • e3sm/init/u.oi30.lr10/topo/cull

The supported unified mesh names are the same as those listed in Unified base-mesh tasks.

Configuration Options

These tasks create shared config files in their work directories:

  • combine_topo.cfg for combine tasks

  • remap_topo.cfg for remap tasks

  • cull_topo.cfg for cull tasks

Combine Tasks

Combine tasks use the [combine_topo] section.

The following options are set automatically from the task path and normally should not be changed by hand:

  • target_grid

  • resolution_latlon

  • resolution_cubedsphere

Common user-tunable options are:

  • method: Remapping method used when combining datasets.

  • renorm_thresh: Threshold below which interpolated fields are not renormalized.

  • ntasks and min_tasks: Target and minimum MPI task counts for remapping.

  • latmin and latmax: Latitude range over which Antarctic and global topography are blended.

  • lat_tiles and lon_tiles: Tile counts used to decompose global remapping.

Visualization tasks also use viz_combine_topo_* sections for colormap and normalization settings.

Remap Tasks

Remap tasks use the shared [spherical_mesh] section together with [remap_topography].

Common user-tunable options are:

  • antarctic_boundary_convention: Antarctic coastline convention used to mask topography before remapping.

  • description: Metadata description written to the remapped product.

  • ntasks and min_tasks: Target and minimum MPI task counts for remapping.

  • renorm_threshold: Minimum land or ocean area fraction required before renormalizing elevation variables.

  • expand_distance and expand_factor: Smoothing controls for remapped topography.

For lower-resolution cubed-sphere source topography, Polaris automatically applies lower ntasks and min_tasks defaults from remap_low_res.cfg.

Visualization steps also use viz_remapped_topo_* sections for plot styling.

Cull Tasks

Cull tasks use the [cull_mesh] section.

Common user-tunable options are:

  • cpus_per_task and min_cpus_per_task: Thread-count settings for culling.

  • include_critical_transects: Whether critical land and ocean transects from geometric_features are enforced during masking.

  • sea_ice_latitude_threshold: Latitude poleward of which ocean transects are widened and sea ice is taken to form, so cells without a usable velocity vertex are removed from the sea-ice domain.

  • land_ice_max_latitude: Southern latitude threshold used to classify critical land transects as land ice.

  • land_ice_min_fraction: Minimum land-ice fraction used in south-pole flood filling for the land-ice mask.

  • min_dc_edge_abs_ratio: For unified meshes, the minimum allowed ratio of the shortest dcEdge in the culled ocean/sea-ice domain to the finest ocean background cell width anywhere in it. This is the CFL guard: the time step is set by the shortest edge globally, and a mesh is already sized for its own finest intended resolution, so an edge that is short only relative to a coarse local background costs nothing.

  • min_dc_edge_ratio and max_dc_edge_ratio: For unified meshes, the allowed range of dcEdge relative to the local ocean background cell width. This is the leak guard: land/river resolution reaching the ocean shows up as a locally anomalous ratio even where the absolute edge length is unremarkable. It is set to catch leaks (the contaminated meshes that motivated it reached 0.29 to 0.34) rather than the rare packing defects that reach 0.51 on the finest meshes, at a different location every build. See the design docs unified_mesh_cull_leak and unified_mesh_dc_edge_noise.

Cull tasks produce three culled meshes: ocean, ocean_no_cavities and land. The land mesh is the exact complement of ocean_no_cavities, so every cell of the base mesh is owned by exactly one of the two, and ocean_no_cavities is always a subset of ocean. The two ocean meshes differ only by the ice-shelf cavity cells, so with the default calving_front convention, which leaves no cavities, they are identical. Critical land transects and critical ocean transects are applied to both ocean meshes in the same way; a cell that a critical ocean passage keeps in the ocean is treated as open water rather than as an ice-shelf cavity.

Cells in which the models could not work are removed from both meshes: the ocean is a C-grid, so each of its cells needs at least two edges shared with another ocean cell, and sea ice is a B-grid, so each cell of ocean_no_cavities poleward of sea_ice_latitude_threshold also needs a vertex whose surrounding cells are all in that mesh, or ice drifting in could never leave. The mask step fails if any of this does not hold, or if removing such cells would close a critical ocean passage, in which case it names the passage.