icon_sc.icon.grid — grid, geometry, metrics

icon_sc.icon grid stack (architecture §3).

S06 ships the vertical grid; S11 adds the horizontal grid on real ICON grid files — the pure NetCDF reader, IconGrid (from_file()), named geometry, and the metrics/interpolation static-state factories.

IconGrid — the ICON horizontal grid (architecture §3.1, S11).

One immutable object per horizontal domain, constructed from an ICON grid NetCDF file and keyed by uuidOfHGrid. Connectivities are exposed in two forms from one storage: raw numpy index arrays (JAX segment-sum patterns, numpy reference components) and the gt4py offset-provider mapping consumed by icon_sc.core.ingress.gt4py programs and icon4py granules. The grid — not the state — owns topology; components receive it at construction time.

Implementation policy (PLAN S11 item 1): construction delegates to pinned icon4py’s GridManager (file parsing, 0-based normalization, derived diamond/butterfly connectivities, start/end domain indices, single-node decomposition) and GridGeometry (geometry fields) — REFERENCES.lock id icon4py-grid-stack. The pure-numpy reader in icon_sc.icon.grid.reader is the independent ingestion path; their equivalence is a datatest (SPEC acceptance 2).

class icon_sc.icon.grid.grid.IconGrid(*, i4_grid, decomposition_info, coordinates, geometry_fields, gt4py_backend)

The ICON horizontal grid (frozen interface, SPEC S11).

Built via from_file(); wraps the icon4py grid object (public accessor icon4py_grid for lane-B components), the decomposition info and the lazy geometry factory. All numpy views are read-only copies; the offset-provider mapping aliases the wrapped grid’s connectivities (zero-copy into gt4py).

Parameters:

  • i4_grid (Any)

  • decomposition_info (Any)

  • coordinates (Any)

  • geometry_fields (Any)

  • gt4py_backend (Any | None)

property uuid: str

uuidOfHGrid of the source grid file.

property limited_area: bool

True for regional (limited-area) grids — boundary refin_ctrl points exist.

property geometry_type: str

"icosahedron" (sphere) or "torus" (planar doubly-periodic).

property connectivities: Mapping[str, ndarray[tuple[int, ...], dtype[int32]]]

offset name -> (horizontal, sparse) int32 table.

0-based, -1 marks missing neighbors (pentagon points; LAM boundaries). Includes the file-sourced tables (C2E, E2C, E2V, C2V, C2E2C, V2E, V2C, V2E2V) and icon4py’s derived ones (E2C2V, E2C2E, E2C2EO, C2E2CO, C2E2C2E, C2E2C2E2C).

Type:

Raw index arrays

property offset_providers: Mapping[str, Any]

The gt4py offset-provider mapping (frozen interface, SPEC S11).

Exactly what gt4py.next programs take as offset_provider=; includes the vertical Koff dimension mapping. Aliases the wrapped icon4py grid’s connectivity storage — do not mutate.

property refin_ctrl: Mapping[str, ndarray[tuple[int, ...], dtype[int32]]]

Grid-refinement control per location (retained for future LAM/nesting §10).

property geometry: Geometry

Named geometry fields (lazy icon4py GridGeometry behind Geometry).

property icon4py_grid: Any

The wrapped icon4py IconGrid (start/end indices, gt4py connectivities).

property icon4py_geometry: Any

The icon4py GridGeometry field source (built lazily, then cached).

property decomposition_info: Any

icon4py DecompositionInfo (single-node here; distributed arrives in P5).

property gt4py_backend: Any | None

The gt4py program processor the grid was built for (None = embedded).

icon_sc.icon.grid.grid.from_file(path, ctx, *, num_levels=1, keep_skip_values=True)

Read an ICON grid NetCDF file into an IconGrid (frozen interface).

ctx selects backend/allocator for the grid buffers and the lazily computed geometry fields (None → embedded/CPU). num_levels sizes the vertical axis the wrapped icon4py grid carries (icon4py bundles it with the horizontal topology; a grid file knows nothing vertical — pass the model’s level count when the grid hosts K-dependent factories, cf. icon_sc.icon.grid.metrics.metrics()). keep_skip_values=True preserves -1 invalid neighbors in the raw index arrays (icon4py’s geometry/factory convention).

Malformed files surface icon4py’s reader errors annotated with the file path.

Raises:

FileNotFoundError – If the file is missing.

Parameters:
Return type:

IconGrid

ICON vertical grid (architecture §3.2, S06).

Everything a physics column needs from the vertical coordinate: the vct_a/vct_b table (ingested, or computed from the SLEVE namelist parameters), nominal interface and full-level heights, the special level indices (flat / Rayleigh-damping / moist-physics), and the ICON reference-atmosphere helpers.

Implementation policy (PLAN S06 item 1): reuse the pinned icon4py vertical-grid machinery internally — icon4py.model.common.grid.vertical carries the ICON init_vert_coord algorithm and the namelist defaults — and adapt it behind the frozen VerticalGrid(vct_a, vct_b, nlev) interface, whose surface speaks numpy, not gt4py fields. The reference atmosphere is the decaying-isothermal profile of mo_vertical_grid.f90 (identical formulas in icon4py metrics/reference_atmosphere.py); the helpers here are array-namespace generic like icon_sc.icon.thermo.

Coordinate convention (ICON): index 0 is the model top; vct_a is decreasing and has nlev + 1 entries (interfaces / half levels).

class icon_sc.icon.grid.vertical.SLEVEConfig(num_levels, lowest_layer_thickness=50.0, maximal_layer_thickness=25000.0, top_height_limit_for_maximal_layer_thickness=15000.0, model_top_height=23500.0, flat_height=16000.0, stretch_factor=1.0, rayleigh_damping_height=45000.0, htop_moist_proc=22500.0, decay_scale_1=4000.0, decay_scale_2=2500.0, decay_exponent=1.2)

SLEVE vertical-coordinate namelist parameters (ICON mo_sleve_nml / nonhydrostatic_nml; defaults = icon4py v0.2.0 VerticalGridConfig = the ICON namelist defaults).

Only the parameters governing the 1-d vct_a/vct_b table and the special level indices live here; the 3-d terrain-following SLEVE surfaces need topography and arrive with the metrics factory (lane B, S11).

Parameters:

  • num_levels (int)

  • lowest_layer_thickness (float)

  • maximal_layer_thickness (float)

  • top_height_limit_for_maximal_layer_thickness (float)

  • model_top_height (float)

  • flat_height (float)

  • stretch_factor (float)

  • rayleigh_damping_height (float)

  • htop_moist_proc (float)

  • decay_scale_1 (float)

  • decay_scale_2 (float)

  • decay_exponent (float)

num_levels: int

Number of full levels (num_lev).

lowest_layer_thickness: float = 50.0

thickness of the lowest layer [m] (<= 0.01 → uniform grid).

Type:

min_lay_thckn

maximal_layer_thickness: float = 25000.0

maximum layer thickness below htop_thcknlimit [m].

Type:

max_lay_thckn

top_height_limit_for_maximal_layer_thickness: float = 15000.0

height below which the thickness limit applies [m].

Type:

htop_thcknlimit

model_top_height: float = 23500.0

model top height [m].

Type:

top_height

flat_height: float = 16000.0

height above which coordinate surfaces are flat [m].

Type:

flat_height

stretch_factor: float = 1.0

stretching factor of the layer distribution.

Type:

stretch_fac

rayleigh_damping_height: float = 45000.0

Rayleigh-damping start height for w [m] (nonhydrostatic_nml).

Type:

damp_height

htop_moist_proc: float = 22500.0

height above which moist physics is switched off [m].

Type:

htop_moist_proc

decay_scale_1: float = 4000.0

decay scale of the large-scale topography component [m].

Type:

decay_scale_1

decay_scale_2: float = 2500.0

decay scale of the small-scale topography component [m].

Type:

decay_scale_2

decay_exponent: float = 1.2

exponent of the SLEVE decay function.

Type:

decay_exp

class icon_sc.icon.grid.vertical.VerticalGrid(vct_a, vct_b, nlev, *, flat_height=16000.0, rayleigh_damping_height=45000.0, htop_moist_proc=22500.0, config=None)

The ICON vertical grid over one column stack (frozen interface, SPEC S06).

VerticalGrid(vct_a, vct_b, nlev) ingests an existing coordinate table (e.g. from an icon4py grid savepoint); from_config() computes the table from SLEVE namelist parameters. Internally adapts icon4py’s VerticalGrid (index semantics are therefore identical to ICON’s nflatlev/nrdmax/kstart_moist).

Parameters:

  • vct_a (npt.ArrayLike)

  • vct_b (npt.ArrayLike | None)

  • nlev (int)

  • flat_height (float)

  • rayleigh_damping_height (float)

  • htop_moist_proc (float)

  • config (SLEVEConfig | None)

classmethod from_config(config)

Compute vct_a/vct_b from SLEVE parameters and build the grid.

Parameters:

config (SLEVEConfig)

Return type:

VerticalGrid

property nlev: int

Number of full levels.

property num_interface_levels: int

nlev + 1.

Type:

Number of interface (half) levels

property vct_a: ndarray[tuple[int, ...], dtype[float64]]

nominal interface heights [m], top first.

Type:

Vertical coordinate table A

property vct_b: ndarray[tuple[int, ...], dtype[float64]] | None

Vertical coordinate table B (w-profile merging table, mo_nh_init_utils).

property interface_heights: ndarray[tuple[int, ...], dtype[float64]]

Nominal (flat-terrain) interface heights [m] — vct_a.

property full_level_heights: ndarray[tuple[int, ...], dtype[float64]]

interface midpoints.

Type:

Nominal full-level (mass-point) heights [m]

property layer_thickness: ndarray[tuple[int, ...], dtype[float64]]

Nominal layer thickness [m] (ddqz_z_full over flat terrain).

property config: SLEVEConfig

The SLEVE namelist parameters this grid was built with.

property icon4py_grid: Any

The wrapped icon4py VerticalGrid (public accessor, declared S11).

S07 flagged the _i4_grid friend access; the S11 metrics factory is the first out-of-module consumer, so the accessor becomes part of the surface. Lane-B wrappers hand this object to pinned icon4py machinery; ICON-sc-side code should keep using the numpy-speaking properties above.

property nflatlev: int

Bottom-most level index at which coordinate surfaces are flat.

property nrdmax: int

End index of the Rayleigh-damping layer for w (ICON nrdmax).

property kstart_moist: int

Start level of moist physics (interface midpoint < htop_moist_proc).

reference_profiles()

ICON reference-atmosphere profiles on nominal full levels.

Keys are the registry names icon:exner_ref_mc / icon:theta_ref_mc / icon:rho_ref_mc (plain numpy arrays, not DataArrays — the static-state packaging is the metrics factory’s job, S11).

Return type:

dict[str, ndarray[tuple[int, …], dtype[float64]]]

icon_sc.icon.grid.vertical.compute_vct_a_and_vct_b(config)

The analytic ICON vertical-coordinate table (SLEVE computation).

Delegates to pinned icon4py get_vct_a_and_vct_b (the init_vert_coord algorithm: vct_a[k] = H*(2/π·arccos((k/N)^s))^d with the lowest-layer-thickness exponent, thickness limiting and stretching; uniform grid when lowest_layer_thickness <= 0.01; vct_b = exp(-vct_a/5000)).

Returns:

(vct_a, vct_b) as numpy fp64 arrays of length num_levels + 1, model top first.

Parameters:

config (SLEVEConfig)

Return type:

tuple[ndarray[tuple[int, …], dtype[float64]], ndarray[tuple[int, …], dtype[float64]]]

icon_sc.icon.grid.vertical.reference_exner(z)

Reference Exner function [1] at height z [m] — exner_ref_mc.

Parameters:

z (Any)

Return type:

Any

icon_sc.icon.grid.vertical.reference_potential_temperature(z)

Reference (virtual) potential temperature [K] — theta_ref_mc.

The ICON reference state is dry, so this doubles as the θv reference.

Parameters:

z (Any)

Return type:

Any

icon_sc.icon.grid.vertical.reference_pressure(z)

Reference pressure [Pa] at height z [m] — Fortran z_aux1.

Parameters:

z (Any)

Return type:

Any

icon_sc.icon.grid.vertical.reference_rho(z)

Reference density [kg m-3] at height z [m] — rho_ref_mc.

Parameters:

z (Any)

Return type:

Any

icon_sc.icon.grid.vertical.reference_temperature(z)

Reference temperature [K] at height z [m] — Fortran z_temp.

Parameters:

z (Any)

Return type:

Any

Named grid-geometry fields (architecture §3.1, S11).

grid.geometry.<named field> (frozen interface) exposes the horizontal geometry — edge lengths, dual lengths, areas, orientation, coriolis — as read-only numpy fp64 arrays. Computation is delegated to pinned icon4py’s GridGeometry field factory (REFERENCES.lock id icon4py-grid-stack): file-sourced quantities (areas, lengths, orientations) pass through; derived ones (edge area, coriolis parameter, far-vertex distance, normals/tangents) are computed lazily on first access with the grid’s backend.

class icon_sc.icon.grid.geometry.Geometry(i4_geometry)

Read-only view of the grid’s geometry fields (frozen interface, SPEC S11).

Attribute access returns numpy fp64 arrays (host copies, write-protected, cached); names() lists the available fields. coriolis_parameter lives on edges (the dycore’s consumer location, icon4py convention).

Parameters:

i4_geometry (Any)

static names()

The named geometry fields this surface provides.

Return type:

tuple[str, …]

get(name)

Fetch a named geometry field as a read-only numpy array.

Parameters:

name (str)

Return type:

ndarray[tuple[int, …], dtype[float64]]

Metrics factory (architecture §3.2, S11).

metrics(grid, vgrid) -> Mapping[str, DataArray] (frozen interface) computes the 3-d metric terms and reference-state fields of ICON’s t_nh_metrics — heights, functional determinants, interpolation weight factors, reference atmosphere, pressure-gradient and Rayleigh/divergence-damping coefficients — as read-only static-state DataArrays under their registry names (icon_sc.icon.names).

Delegates to pinned icon4py’s MetricsFieldsFactory (wrap-don’t-rewrite, PLAN S11 item 1; REFERENCES.lock id icon4py-metrics-interp-factories); the vertical grid enters through the S06 VerticalGrid via its icon4py_grid accessor. The field list is exactly the S12/S13 consumption set: icon4py dycore_states.MetricStateNonHydro plus the DiffusionMetricState extras (zd_*) and the S06 height/thickness registry rows — REFERENCES.lock id icon4py-dycore-diffusion-static-state.

icon_sc.icon.grid.metrics.METRICS_FIELDS: Final[Mapping[str, FieldSpec]] = mappingproxy({'altitude': FieldSpec(name='altitude', i4_name='height', dims=('cell', 'height'), location='cell'), 'altitude_on_interface_levels': FieldSpec(name='altitude_on_interface_levels', i4_name='vertical_coordinates_on_half_levels', dims=('cell', 'height_interface'), location='cell'), 'icon:ddqz_z_full': FieldSpec(name='icon:ddqz_z_full', i4_name='functional_determinant_of_metrics_on_full_levels', dims=('cell', 'height'), location='cell'), 'icon:inv_ddqz_z_full': FieldSpec(name='icon:inv_ddqz_z_full', i4_name='inverse_of_functional_determinant_of_metrics_on_full_levels', dims=('cell', 'height'), location='cell'), 'icon:ddqz_z_half': FieldSpec(name='icon:ddqz_z_half', i4_name='functional_determinant_of_metrics_on_interface_levels', dims=('cell', 'height_interface'), location='cell'), 'icon:ddqz_z_full_e': FieldSpec(name='icon:ddqz_z_full_e', i4_name='functional_determinant_of_metrics_on_full_levels_on_edges', dims=('edge', 'height'), location='edge'), 'icon:scalfac_dd3d': FieldSpec(name='icon:scalfac_dd3d', i4_name='scaling_factor_for_3d_divergence_damping', dims=('height',), location='scalar'), 'icon:rayleigh_w': FieldSpec(name='icon:rayleigh_w', i4_name='rayleigh_w', dims=('height_interface',), location='scalar'), 'icon:coeff1_dwdz': FieldSpec(name='icon:coeff1_dwdz', i4_name='coeff1_dwdz', dims=('cell', 'height'), location='cell'), 'icon:coeff2_dwdz': FieldSpec(name='icon:coeff2_dwdz', i4_name='coeff2_dwdz', dims=('cell', 'height'), location='cell'), 'icon:exner_ref_mc': FieldSpec(name='icon:exner_ref_mc', i4_name='exner_ref_mc', dims=('cell', 'height'), location='cell'), 'icon:theta_ref_mc': FieldSpec(name='icon:theta_ref_mc', i4_name='theta_ref_mc', dims=('cell', 'height'), location='cell'), 'icon:rho_ref_mc': FieldSpec(name='icon:rho_ref_mc', i4_name='rho_ref_mc', dims=('cell', 'height'), location='cell'), 'icon:theta_ref_ic': FieldSpec(name='icon:theta_ref_ic', i4_name='theta_ref_ic', dims=('cell', 'height_interface'), location='cell'), 'icon:d_exner_dz_ref_ic': FieldSpec(name='icon:d_exner_dz_ref_ic', i4_name='d_exner_dz_ref_ic', dims=('cell', 'height_interface'), location='cell'), 'icon:theta_ref_me': FieldSpec(name='icon:theta_ref_me', i4_name='theta_ref_me', dims=('edge', 'height'), location='edge'), 'icon:rho_ref_me': FieldSpec(name='icon:rho_ref_me', i4_name='rho_ref_me', dims=('edge', 'height'), location='edge'), 'icon:d2dexdz2_fac1_mc': FieldSpec(name='icon:d2dexdz2_fac1_mc', i4_name='d2dexdz2_fac1_mc', dims=('cell', 'height'), location='cell'), 'icon:d2dexdz2_fac2_mc': FieldSpec(name='icon:d2dexdz2_fac2_mc', i4_name='d2dexdz2_fac2_mc', dims=('cell', 'height'), location='cell'), 'icon:ddxn_z_full': FieldSpec(name='icon:ddxn_z_full', i4_name='ddxn_z_full', dims=('edge', 'height'), location='edge'), 'icon:ddxt_z_full': FieldSpec(name='icon:ddxt_z_full', i4_name='ddxt_z_full', dims=('edge', 'height'), location='edge'), 'icon:vwind_impl_wgt': FieldSpec(name='icon:vwind_impl_wgt', i4_name='implicitness_weight_for_exner_and_w_in_vertical_dycore_solver', dims=('cell',), location='cell'), 'icon:vwind_expl_wgt': FieldSpec(name='icon:vwind_expl_wgt', i4_name='explicitness_weight_for_exner_and_w_in_vertical_dycore_solver', dims=('cell',), location='cell'), 'icon:exner_exfac': FieldSpec(name='icon:exner_exfac', i4_name='exner_exfac', dims=('cell', 'height'), location='cell'), 'icon:wgtfac_c': FieldSpec(name='icon:wgtfac_c', i4_name='wgtfac_c', dims=('cell', 'height_interface'), location='cell'), 'icon:wgtfac_e': FieldSpec(name='icon:wgtfac_e', i4_name='wgtfac_e', dims=('edge', 'height_interface'), location='edge'), 'icon:wgtfacq_c': FieldSpec(name='icon:wgtfacq_c', i4_name='weighting_factor_for_quadratic_interpolation_to_cell_surface', dims=('cell', 'height'), location='cell'), 'icon:wgtfacq_e': FieldSpec(name='icon:wgtfacq_e', i4_name='weighting_factor_for_quadratic_interpolation_to_edge_center', dims=('edge', 'height'), location='edge'), 'icon:pg_exdist': FieldSpec(name='icon:pg_exdist', i4_name='distance_for_pressure_gradient_extrapolation', dims=('edge', 'height'), location='edge'), 'icon:mask_prog_halo_c': FieldSpec(name='icon:mask_prog_halo_c', i4_name='mask_prog_halo_c', dims=('cell',), location='cell'), 'icon:hmask_dd3d': FieldSpec(name='icon:hmask_dd3d', i4_name='horizontal_mask_for_3d_divdamp', dims=('edge',), location='edge'), 'icon:zdiff_gradp': FieldSpec(name='icon:zdiff_gradp', i4_name='zdiff_gradp', dims=('edge', 'e2c', 'height'), location='edge'), 'icon:vertoffset_gradp': FieldSpec(name='icon:vertoffset_gradp', i4_name='vertoffset_gradp', dims=('edge', 'e2c', 'height'), location='edge'), 'icon:nflat_gradp': FieldSpec(name='icon:nflat_gradp', i4_name='nflat_gradp', dims=(), location='scalar'), 'icon:coeff_gradekin': FieldSpec(name='icon:coeff_gradekin', i4_name='coeff_gradekin', dims=('edge', 'e2c'), location='edge'), 'icon:zd_diffcoef': FieldSpec(name='icon:zd_diffcoef', i4_name='zd_diffcoef', dims=('cell', 'height'), location='cell'), 'icon:zd_intcoef': FieldSpec(name='icon:zd_intcoef', i4_name='zd_intcoef', dims=('cell', 'c2e2c', 'height'), location='cell'), 'icon:zd_vertoffset': FieldSpec(name='icon:zd_vertoffset', i4_name='zd_vertoffset', dims=('cell', 'c2e2c', 'height'), location='cell')})

The metric fields S12 (solve_nonhydro) + S13 (diffusion) consume, keyed by registry name. icon4py names from metrics_attributes.py (pinned v0.2.0). K-profile fields (height/height_interface only) carry location="scalar" — they live on no horizontal mesh location; icon:nflat_gradp is a 0-d int level index.

icon_sc.icon.grid.metrics.metrics(grid, vgrid, *, topography=None, config=None, interpolation_config=None, fields=None)

Compute the static metric fields (frozen interface, SPEC S11).

grid must have been built with num_levels == vgrid.nlev (the wrapped icon4py grid bundles the vertical size with the horizontal topology). Keyword extensions (declared, SPEC allows additive defaults): topography — cell field of surface heights [m], None → flat terrain; config / interpolation_config — icon4py MetricsConfig / InterpolationConfig (None → ICON namelist defaults); fields — registry-name subset of METRICS_FIELDS (default: all).

Returns:

A read-only mapping registry-name → read-only DataArray with grid_uuid provenance; being static, the fields are exempt from halo tracking (§3.2).

Parameters:

  • grid (IconGrid)

  • vgrid (VerticalGrid)

  • topography (npt.ArrayLike | None)

  • config (Any | None)

  • interpolation_config (Any | None)

  • fields (Iterable[str] | None)

Return type:

Mapping[str, xr.DataArray]

Interpolation-coefficient factory (architecture §3.2, S11).

interpolation(grid) -> Mapping[str, DataArray] (frozen interface) computes the horizontal interpolation coefficients the dycore and diffusion consume — RBF vector coefficients, cell/edge/vertex weights, geometric factors, nudging coefficients — as read-only static-state DataArrays under their registry names (icon_sc.icon.names).

Delegates to pinned icon4py’s InterpolationFieldsFactory (wrap-don’t-rewrite, PLAN S11 item 1; REFERENCES.lock id icon4py-metrics-interp-factories). The field list is exactly the S12/S13 consumption set: icon4py dycore_states.InterpolationState plus diffusion_states.DiffusionInterpolationState (a subset) — REFERENCES.lock id icon4py-dycore-diffusion-static-state.

icon_sc.icon.grid.interpolation.INTERPOLATION_FIELDS: Final[Mapping[str, FieldSpec]] = mappingproxy({'icon:c_lin_e': FieldSpec(name='icon:c_lin_e', i4_name='interpolation_coefficient_from_cell_to_edge', dims=('edge', 'e2c'), location='edge'), 'icon:e_bln_c_s': FieldSpec(name='icon:e_bln_c_s', i4_name='bilinear_edge_cell_weight', dims=('cell', 'c2e'), location='cell'), 'icon:geofac_div': FieldSpec(name='icon:geofac_div', i4_name='geometrical_factor_for_divergence', dims=('cell', 'c2e'), location='cell'), 'icon:geofac_rot': FieldSpec(name='icon:geofac_rot', i4_name='geometrical_factor_for_curl', dims=('vertex', 'v2e'), location='vertex'), 'icon:geofac_n2s': FieldSpec(name='icon:geofac_n2s', i4_name='geometrical_factor_for_nabla_2_scalar', dims=('cell', 'c2e2co'), location='cell'), 'icon:geofac_grdiv': FieldSpec(name='icon:geofac_grdiv', i4_name='geometrical_factor_for_gradient_of_divergence', dims=('edge', 'e2c2eo'), location='edge'), 'icon:geofac_grg_x': FieldSpec(name='icon:geofac_grg_x', i4_name='geometrical_factor_for_green_gauss_gradient_x', dims=('cell', 'c2e2co'), location='cell'), 'icon:geofac_grg_y': FieldSpec(name='icon:geofac_grg_y', i4_name='geometrical_factor_for_green_gauss_gradient_y', dims=('cell', 'c2e2co'), location='cell'), 'icon:nudgecoeff_e': FieldSpec(name='icon:nudgecoeff_e', i4_name='nudging_coefficients_for_edges', dims=('edge',), location='edge'), 'icon:rbf_vec_coeff_v1': FieldSpec(name='icon:rbf_vec_coeff_v1', i4_name='rbf_interpolation_coefficient_vertex_1', dims=('vertex', 'v2e'), location='vertex'), 'icon:rbf_vec_coeff_v2': FieldSpec(name='icon:rbf_vec_coeff_v2', i4_name='rbf_interpolation_coefficient_vertex_2', dims=('vertex', 'v2e'), location='vertex'), 'icon:rbf_vec_coeff_e': FieldSpec(name='icon:rbf_vec_coeff_e', i4_name='rbf_interpolation_coefficient_edge', dims=('edge', 'e2c2e'), location='edge'), 'icon:c_intp': FieldSpec(name='icon:c_intp', i4_name='cell_to_vertex_interpolation_factor_by_area_weighting', dims=('vertex', 'v2c'), location='vertex'), 'icon:pos_on_tplane_e_x': FieldSpec(name='icon:pos_on_tplane_e_x', i4_name='pos_on_tplane_e_x', dims=('edge', 'e2c'), location='edge'), 'icon:pos_on_tplane_e_y': FieldSpec(name='icon:pos_on_tplane_e_y', i4_name='pos_on_tplane_e_y', dims=('edge', 'e2c'), location='edge'), 'icon:e_flx_avg': FieldSpec(name='icon:e_flx_avg', i4_name='e_flux_average', dims=('edge', 'e2c2eo'), location='edge')})

The interpolation fields S12 (solve_nonhydro) + S13 (diffusion) consume, keyed by registry name. icon4py names from interpolation_attributes.py (pinned v0.2.0).

icon_sc.icon.grid.interpolation.interpolation(grid, *, config=None, fields=None)

Compute the static interpolation coefficients (frozen interface, SPEC S11).

config is an icon4py InterpolationConfig (None → ICON namelist defaults); fields selects a subset of INTERPOLATION_FIELDS by registry name (default: all).

Returns:

A read-only mapping registry-name → read-only DataArray (dims/location stamped, grid_uuid provenance).

Parameters:

  • grid (IconGrid)

  • config (Any | None)

  • fields (Iterable[str] | None)

Return type:

Mapping[str, xr.DataArray]

ICON grid NetCDF reader (architecture §3.1, S11) — pure numpy, no gt4py.

Reads the grid files Zonda / the DWD grid generator / the MPI-M grid generator produce into plain numpy arrays: sizes, uuidOfHGrid, connectivity index tables, primal/dual geometry, coordinates and refin_ctrl. The variable names, layouts and index normalization are transcribed from pinned icon4py’s grid/gridfile.py / grid/grid_manager.py (REFERENCES.lock id icon4py-grid-stack); equivalence with icon4py’s grid object is asserted in tests/test_icon_grid_datatest.py.

Kept free of gt4py imports on purpose (PLAN S11 pitfall): the reader stays reusable in P4 tooling and keeps the dependency surface of pure ingestion minimal. The gt4py-facing IconGrid wrapper lives in icon_sc.icon.grid.grid.

Normalization (identical to icon4py’s ToZeroBasedIndexTransformation):

  • connectivity tables are stored transposed in the file — (sparse, horizontal) — and 1-based; the reader transposes to (horizontal, sparse) and subtracts 1, keeping the invalid marker -1 untouched;

  • refin_ctrl and orientation tables are read as int32 without index offset;

  • coordinates are radians (both MPI-M and DWD files); torus files add cartesian center coordinates.

class icon_sc.icon.grid.reader.GridFileData(path, uuid, n_cells, n_edges, n_vertices, grid_root, grid_level, geometry_type, limited_area, has_refin_ctrl, connectivities, refin_ctrl, geometry, orientations, coordinates, sphere_radius=None, domain_length=None, domain_height=None)

Plain-numpy content of one ICON grid NetCDF file (all arrays read-only).

connectivities are 0-based (horizontal, sparse) int32 tables with -1 marking missing neighbors; refin_ctrl maps location name to the raw refinement control field (all-zeros when the file carries none — has_refin_ctrl records which); limited_area follows icon4py’s criterion (any cell refin_ctrl > 0).

Parameters:
exception icon_sc.icon.grid.reader.GridFileError

A grid file is missing required content or has an unexpected layout.

icon_sc.icon.grid.reader.read_grid_file(path)

Read an ICON grid NetCDF file into GridFileData (frozen surface, S11).

Raises:
Parameters:

path (str | Path)

Return type:

GridFileData