Web Interface¶

The Zonda web interface, available at zonda.ethz.ch , serves as the primary platform for users to configure and submit data requests. It provides an intuitive and interactive environment for managing templates, parameters, and domains.

The main features of this frontend are:

Configure the desired grid and EXTPAR options directly in the web UI.
Preview the domain on either a 2D map or a 3D globe.
Generate up to six (nested) domains simultaneously.
Generate a JSON file that serves as input for the backend to generate the data.

Basic and Expert Mode¶

A toggle in the top-right corner of the page switches between Basic and Expert mode. Basic mode exposes only the most commonly needed settings, keeping the interface clean for straightforward setups. Expert mode reveals additional parameters for advanced configuration.

Select a Template (Optional)¶

You can choose from a wide range of Templates, derived from operational setups of the ICON community. Selecting a template applies all its settings to the frontend automatically.

The following templates are available:

DWD — operational domains from the German Weather Service (DWD ):

ICON-Global-Eu: Global domain (R3B7) with a regional nest covering Europe (2 domains)
ICON-D2: Regional domain (R19B7) covering Germany, Switzerland and Austria

MeteoSwiss — operational domains from MeteoSwiss (MeteoSwiss ):

ICON-CH1: Domain at ~1 km resolution (R19B8) covering Switzerland and surrounding area
ICON-CH2: Domain at ~2 km resolution (R19B7) covering Switzerland and surrounding area

CORDEX-CMIP6 — standard CORDEX-CMIP6 domains domains at 0.12° resolution (CORDEX ):

AFR-12: Africa
ANT-12: Antarctica
ARC-12: Arctic
AUS-12: Australasia
CAM-12: Central America
CAS-12: Central Asia
EAS-12: East Asia
EUR-12: Europe
MED-12: Mediterranean
MNA-12: Middle East and North Africa
NAM-12: North America
SAM-12: South America
SEA-12: Southeast Asia
WAS-12: West Asia

Zonda Parameters¶

Set the name of the request — this string appears in the ICON grid output files, EXTPAR output files, and the final zip file.

The backend supports different tagged versions of DWD ICON Tools and EXTPAR. By default, the latest version is used; select a fixed version here if needed.

Global Parameters¶

In the Global Parameters section, define the grid values n (grid_root) and k (grid_level) for the ICON base grid.

Tip

Use the RnBk Finder Tool in the right sidebar to derive suitable n and k values from a target grid spacing in km.

Expert Mode

When Expert Mode is enabled, two additional parameter groups become available:

Icorotation — controls the orientation of the base icosahedron:

icorotation: Additional rotation angle (in degrees) around the north pole applied after the base grid is generated.
icopole_lat: Latitude of the rotated icosahedron pole.
icopole_lon: Longitude of the rotated icosahedron pole.

Metadata — WMO identification codes embedded in the output files:

centre: WMO originating centre code (e.g. 78 = DWD, 215 = MCH/ETHZ, 252 = MPIM).
subcentre: WMO sub-centre code (0–255).

Domain Specific Parameters¶

Domain 1 is always present. Add further domains by clicking the icon, and remove them with the icon.

Switch between domains by clicking on them. This action updates the view of the subsections below (Domain Settings and EXTPAR Parameters).

Map Preview¶

Once valid grid numbers are entered, your domain(s) will appear in the preview on the left-hand side. Toggle between 2D (map) and 3D (globe) views as needed.

Both views support two background layers: the standard OpenStreetMap (OSM) layer and a topography layer. Use the layer buttons in the top-right corner of the preview to switch between them.

For domains near the poles, the interface automatically switches to 3D view and disables the 2D map, as not all edge cases for polar visualizations are covered in 2D.

Domain Settings¶

On the top, an Estimations box shows the grid name (RnBk values), an estimated grid spacing in km, as well as the number of grid cells based on your domain settings below.

Grid Generation Mode¶

The Grid Generation Mode buttons control how the ICON grid for a domain is obtained:

Create — the grid is generated from scratch based on the domain geometry you define (center, half-widths, shape, etc.). This is the default mode and gives full control over the domain configuration.
Select — use a pre-existing grid file from the ICON Grid File Server, including additional grids provided by institutions such as MeteoSwiss. A Settings box appears below the mode selector where you can choose the institution and grid file. Note that no map preview is available for pre-defined grids, and when Domain 1 is in Select mode the Global Parameters (n/k values) are disabled, as they are determined by the chosen file.

Note that with multiple domains you can mix the two modes as you please, with three possible outcomes depending on the combinations:

When a domain using Create is followed by one or more domains using Create, they will all be passed to ICON Tools as one (nesting) group and nested domains will be generated based on the resolution of the first domain. For each sub-domain the grid spacing is halved.
When a domain using Select is followed by one or more domains using Select, they will all be treated as independent (nesting) groups, each containing a single domain.
When a domain using Select is followed by one or more domains using Create, they will all be passed to ICON Tools as one (nesting) group and nested domains will be generated starting from the grid file provided for the first domain using Select.

Settings¶

Tip

Tooltips are available for all user-configurable variables. Hover over the icon to view them.

The following parameter is always visible:

parent_id: Parent grid ID. For example, if Domain 2 is nested within Domain 1, set parent_id to 1 for Domain 2.

The next control is the region_type dropdown, which defines the shape and type of the domain:

Value	Label	Description
1	Global	A global domain covering the entire globe.
2	Circular	A circular domain defined by a center point and a radius.
3	Rectangular	A rectangular domain defined by a center point and half-widths in latitude and longitude.
4	Expression	A domain defined by a custom boolean expression using `[lat]` and `[lon]` keywords. No map preview is available for this type.

For region_type 2 (Circular) and 3 (Rectangular), the center coordinates are also shown:

center_lat: Center point in degrees latitude.
center_lon: Center point in degrees longitude.

Additional parameters depend on the selected region_type:

Circular (region_type = 2):

radius: Radius of the circular domain in degrees.

Rectangular (region_type = 3):

hwidth_lat: Half-width in degrees latitude.
hwidth_lon: Half-width in degrees longitude.

Enable the Use a rotated grid checkbox to configure a rotated coordinate system. When checked, the following parameters become configurable:

pole_lat: Latitude of the rotated north pole (in degrees).
pole_lon: Longitude of the rotated north pole (in degrees).

A successful request for a rotated domain produces two additional output files:

<domain>_DOM0x_latlon_rotated.nc: a latitude/longitude netCDF grid file in rotated coordinates that matches your defined domain.

These files can be used to remap unstructured ICON output onto a regular rotated grid, which is particularly useful for the CLM community and regional climate modeling workflows.

Expression (region_type = 4):

expression: A string expression defining which grid cells belong to the domain, evaluated per cell. Use [lat] and [lon] as placeholders for the cell's latitude and longitude. The expression must return a non-zero value for cells that should be included. Example: if([lat] < 60.0, 1, 0). No map preview is available for expression-type domains. See the ICON Tools documentation for more information about supported operators and keywords.

EXTPAR Parameters¶

This section contains all variables required by EXTPAR. For more information, click on a variable name to navigate to the relevant section of the EXTPAR documentation .

The following parameters are always visible:

ilu_type: Land use dataset — Globcover2009, GLC2000, or Ecoclimap-SG.
ialb_type: Albedo type — total albedo, soil albedo, or total albedo without NI and UV fields.
isoil_type: Soil dataset — FAO, HWSD, or HWSD with Terra mapping.
itopo_type: Orography dataset — GLOBE, ASTER, or MERIT. Note that ASTER domains cannot exceed 60°N or 60°S.
it_cl_type: Climatological temperature dataset — fine data over land only, or coarse data over sea combined with fine data over land.
iera_type: ERA climatology type — ERA5 or ERA-I.
iemiss_type: Emissivity dataset — full-range or long-wave.
iaot_type: Aerosol optical thickness (AOT) data source — Tegen or AeroCom.

Expert Mode

When Expert Mode is enabled, the following additional EXTPAR parameters become available:

ilookup_table_lu: Lookup table for land use classification (shown when ilu_type is GLC2000 or GLOBCOVER).
tcorr_lapse_rate: Lapse rate for correction of the climatological 2m temperature (shown when it_cl_type uses temperature climatology correction).
tcorr_offset: Offset for correction of the climatological 2m temperature (same condition as above).
enable_cdnc: Enable the use of Cloud Droplet Number Concentration (CDNC) data.
icdnc_type: CDNC data source — MODIS Q06, MODIS G18, or MODIS BR17 (shown when enable_cdnc is enabled).
enable_edgar: Enable the use of EDGAR emission data.
enable_art: Enable the use of ART aerosol data.
enable_gfasclim: Enable the use of wildfire emissions data.
l_terra_urb: Use TERRA-URB (shown when ilu_type is ECOCLIMAP-SG).
l_use_corine: Use the CORINE land use dataset instead of the default (shown when ilu_type is GLOBCOVER).
infill_corine: Use a custom CORINE dataset where voids are infilled with GLOBCOVER data (shown when l_use_corine is true).
lradtopo: Enable radiation-corrected topography parameters.
radtopo_radius: Radial distance (in metres) considered for horizon computation (shown when lradtopo is enabled).
nhori: Number of horizon angles (shown when lradtopo is enabled).

In addition, a topography plot option becomes available to include a topography visualisation in the EXTPAR output.

Hidden options¶

There are some options for the ICON Grid Generator and EXTPAR which are supported, but not visible on the Zonda frontend. These are generally advanced options only required by very specific users. They are not shown on the frontend to avoid cluttering the interface for more general users, but can still be used by manually adding them to the JSON config before submitting a Zonda request on GitHub. Below you can find a list of these hidden options (refer to the ICON Tools and EXTPAR documentations for more details).

Part of the globals section in the JSON config and passed as an argument to ICON Tools:

lspring_dynamics
beta_spring
maxit
lfixed_boundary
ncells_localize, only available from icontools-2.8.1 on.
bdy_indexing_depth

Part of the icontools section in the JSON config:

number_of_grid_used
expression_var, only available for region_type=4 (see the ICON Tools docs). This is meaningful only when running Zonda locally or if you have access to the IACDIPL-7 server at ETHZ, because it requires a path to a NetCDF file containing the desired variable.

Part of the extpar section in the JSON config:

lurban

JSON Request¶

The web interface automatically generates a config in the form of a JSON code snippet based on the values entered in the sections above.

To proceed:

Use the "Copy and submit config" button.
In the resulting popup, click "Open Request", which redirects you to the data request issue on GitHub.
Follow these steps on GitHub:
- Replace the line PASTE_YOUR_REQUEST_HERE with the JSON code (automatically copied to your clipboard).
- Click "Preview" in the issue box to verify the JSON formatting and syntax highlighting.
- Submit the request by clicking the "Create" button at the bottom right.
- Later, you can also re-submit requests. For example if the request fails due to an error in the JSON file, simply fix the error by editing the JSON snippet in the description of the issue, then re-submit the request by writing a comment containing the string "rerun request". Note that this only works if the issue is not closed and the request is not already running.

Important

The zonda-request repository is publicly accessible. However, to create a new data request issue (and submit a request), you must have a GitHub user account .

Example JSON request¶

The example below shows most of the features of the JSON config available as of v2.2. Additionally, some comments are provided highlighting the changes from v1.x.

{
  "zonda": {
    "request_name": "my_request",
    "backend_tag": "v2.2",
    "icontools_tag": "latest",
    "extpar_tag": "latest"
  },
  "globals": {
    "keep_basegrid_files": false,
    "grid_root": 13,
    "grid_level": 5,
    "icorotation": 0,
    "icopole_lat": 90,
    "icopole_lon": 0,
    "centre": 215,
    "subcentre": 0
  },
  "domains": [
    {
      "domain_id": 1,
      "icontools": {
        "parent_id": 0,
        "region_type": 3,
        "center_lat": 49.5,
        "center_lon": 11.5,
        "hwidth_lat": 22.5,
        "hwidth_lon": 33.5,
        "lrotate": false,
        "pole_lat": 90,
        "pole_lon": -180
      },
      "extpar": {
        "use_array_cache": false,
        "iaot_type": 1,
        "ilu_type": 1,
        "ialb_type": 1,
        "isoil_type": 1,
        "itopo_type": 1,
        "it_cl_type": 1,
        "iera_type": 1,
        "iemiss_type": 1,
        "lradtopo": false,
        "enable_cdnc": false,
        "enable_edgar": false,
        "enable_art": false,
        "enable_gfasclim": false,
        "l_terra_urb": false,
        "l_use_corine": false,
        "infill_corine": false,
        "radtopo_radius": 40000,
        "nhori": 24,
        "ilookup_table_lu": 1,
        "tcorr_lapse_rate": 0.0065,
        "tcorr_offset": 0
      },
      "extpar_plots": [  // You can specify EXTPAR variables that you want to plot on a 2D map.
        { "variable_name": "topography_c" }
      ]
    },
    {
      "domain_id": 2,
      "input_grid": {
        "filepath": "",
        "institution": "mch",  // This is ignored if "filepath" is provided.
        "filename": "icon_grid_0001_R19B08_mch.nc"  // This is ignored if "filepath" is provided.
      },
      "extpar": {
        "use_array_cache": false,
        "iaot_type": 1,
        "ilu_type": 1,
        "ialb_type": 1,
        "isoil_type": 1,
        "itopo_type": 1,
        "it_cl_type": 1,
        "iera_type": 1,
        "iemiss_type": 1,
        "lradtopo": false,
        "enable_cdnc": false,
        "enable_edgar": false,
        "enable_art": false,
        "enable_gfasclim": false,
        "l_terra_urb": false,
        "l_use_corine": false,
        "infill_corine": false,
        "radtopo_radius": 40000,
        "nhori": 24,
        "ilookup_table_lu": 1,
        "tcorr_lapse_rate": 0.0065,
        "tcorr_offset": 0
      },
      "extpar_plots": []  // Zonda cannot plot anything for domains using an input grid, doing this explicitly avoids warning messages.
    },
    {
      "domain_id": 3,
      "icontools": {
        "parent_id": 2,
        "region_type": 3,
        "center_lat": 49.5,
        "center_lon": 11.5,
        "hwidth_lat": 18.225,
        "hwidth_lon": 27.135,
        "lrotate": false,
        "pole_lat": 90,
        "pole_lon": -180
      },
      "extpar": {
        "use_array_cache": false,
        "iaot_type": 1,
        "ilu_type": 1,
        "ialb_type": 1,
        "isoil_type": 1,
        "itopo_type": 1,
        "it_cl_type": 1,
        "iera_type": 1,
        "iemiss_type": 1,
        "lradtopo": false,
        "enable_cdnc": false,
        "enable_edgar": false,
        "enable_art": false,
        "enable_gfasclim": false,
        "l_terra_urb": false,
        "l_use_corine": false,
        "infill_corine": false,
        "radtopo_radius": 40000,
        "nhori": 24,
        "ilookup_table_lu": 1,
        "tcorr_lapse_rate": 0.0065,
        "tcorr_offset": 0
      },
      "extpar_plots": [
        { "variable_name": "topography_c" },
        { "variable_name": "LU_CLASS_FRACTION", "nclass_lu": 2 }  // This is how you can plot a variable with multiple dimensions.
                                                                  // You must specify an index for all additional dimensions as done here for "nclass_lu".
      ]
    },
    {
      "domain_id": 4,
      "icontools": {
        "parent_id": 0,
        "region_type": 4,  // Expression type: domain defined by a custom expression instead of geometric bounds.
        "expression": "if([lat] < 60.0, 1, 0)"  // Include all cells south of 60°N. Use [lat] and [lon] as keywords.
      },
      "extpar": {
        "use_array_cache": false,
        "iaot_type": 1,
        "ilu_type": 1,
        "ialb_type": 1,
        "isoil_type": 1,
        "itopo_type": 1,
        "it_cl_type": 1,
        "iera_type": 1,
        "iemiss_type": 1,
        "lradtopo": false,
        "enable_cdnc": false,
        "enable_edgar": false,
        "radtopo_radius": 40000,
        "nhori": 24,
        "enable_art": false,
        "l_terra_urb": false,
        "l_use_corine": false,
        "infill_corine": false,
        "ilookup_table_lu": 1,
        "tcorr_lapse_rate": 0.0065,
        "tcorr_offset": 0
      },
      "extpar_plots": []
    }
  ]
}

The sidebar on the right offers additional information and tools.

Table of Contents¶

The table of contents ("On this Page") shows all the available sections. A green marker also indicates the current section in the main frame. It is also possible to click on a section in the sidebar to automatically scroll to it.

How to cite Zonda¶

If you use Zonda-generated data for your publications or reports, please copy the text to acknowledge the developers and their institutions.

RnBk Finder Tool¶

Enter a target resolution in km to find the best matching RnBk values. Up to three candidate grids are shown, each with their approximate mesh size and deviation from the requested resolution.