# ICON Grid Manager
###### tags: `cycle 14`

- Developers: Magdalena Luz, Will Sawyer
- Appetite: 1/2 cycle?

## Goal
Develop a first version of a GridManager for icon4py. It should provide information about the ICON grid. It manages information necessary to access ICON fields, like connectivities, grid size, vertical domain boundary indices.
The goal of this project is write a (single node) GridManager in Python that
- reads connectivity data from the grid files
- provides an interface to access the connectivity fields
- calculates the domain boundaries based on the Horizontal Marker indices
- provides an interface corresponding to the ICON `get_indices_[c, v, e]` to read the horizontal domain boundaries, there is a preliminary version of this in `icon4py`: `IconGrid.get_indices_from_to()` which should be refactored.
- in icon4py replace the current icon_grid and grid- savepoint by the new gridmanager.

Reading the connectivity fields should be straightforward. The calculation of the boundary fields needs some evaluation and understanding of ICON code.
MCH has been looking at it while developing and could provide some insights.

The grid manager should provide for nested fields by being able to manage several grids.

## Solution
Could roughly be along this lines: see [documentation](https://hackmd.io/3SmFjjuoQuGbM3TRe2fdhQ)


Usage would be:

config = GridConfiguration(...)
grid_manager = GridManager(config)
grid_manager.init() # reads the grid files, and calculates domain boundaries

(...)

grid: IconGrid = grid_manager.get_icon_grid()
(..)

- [see also this document for some details](https://hackmd.io/3SmFjjuoQuGbM3TRe2fdhQ)
- Further inspiration:
- MCH has already look at that before for the dsl integration. Check with them.
- Have a look at the simplified t_patch by the DG dycore of Florian Prill.
## Steps
- [ ] read grid file
- [x] dimensions
- [x] connectivity arrays
- [ ] transform connectivities:
- [x] zero based
- [x] invalid number: grid file: `INVALID = -1`,
- [x] specialities in ICON and open questions:
- [x] in some cases ICON replaces INVALID values with the last valid index neigbhor? for example `v2c`: in serialized index arrays the invalid numbers are like this: `index(i) = index of last valid neighbor, if index_nc(i) == INVALID` -> *we keep the INVALID value so far*
- [ ] `e2c2v: diamond vertices (reconstructed, not directly read): for boundary edges, there are only the 2 vertices directly adjacent to the edge in ICON, not 3 of them. So the far-vertex (edge normal) of the cell that exists is not there. Why? How should we handle? -> *open*

- [x] test LAM: mch_ch_r04b09_dsl
- [ ] test global grid: aquaplanet

- [x] calculate horizontal zone boundaries: `get_indices_[c,e,v]`, (`refin_ctl`. etc)
- [x] define interface.

    class IconGrid:
    
    
    def get_end_index(d:Dimension, m:int) -> int:
       pass

- [x] Refactoring of grid:
- [x] separate horizontal and vertical grid
- [x] extract connectivity transform: python specific implmentation
- [x] use in diffusion
- [ ] use in dummy_driver

## No Gos
- the project focuses on a single node version, no distribution of the grid needs to be done.
- Fortran ICON uses a layout of fields like (nproma, klevels, n_blks[e, v, c]), the data in the gridfile seems in a linear fashion. No reshaping to the 2d horizontal structure of the Fortran codes needs to done.
- Ignore nesting for now

## Open points/TODOs

- [x] check the [MCH script](https://github.com/dawn-ico/grid-experiments).
- [x] @Magdalena ask Florian for [DG](https://gitlab.dkrz.de/fprill/code-snippets/-/snippets/48) version access