# Icon4py Repo walkthrough

## Structure of the repo
- different packages
- up to now each package is a top level folder in the repo. Discussion: should we change?
- content of the packages
- `atm_dyn_iconam`: dycore stencils, diffusion granule, dycore granule
- `advection`: tracer advection stencils
- `pyutils`: icon4pygen, f2ser (serialization),
- `liskov`: icon_liskov
- `py2f` : Fortran interface generation for granules (untested, branch `fortran_interface_generation`)
- `common`: common functionality for icon: dimensions, grid_manager
- `testutils`: test functionality

## Branches
- `greenline-dycore`: base branch for greenline. Contains the diffusion granule and some basic infrastructure. It is still based on the gt4py by Till: `git+https://github.com/tehrengruber/gt4py.git@reduce_foast_lowering_complexity#egg=gt4py`.

- `implement_nh_solve`: python port of solve_nonhydro
- `implement_velocity_advection`: python port of velocity advection (for solve_nonhydro)
- ` dummy_dycore_driver`: simple python program that runs diffusion module and does a dummy timestepping (serves slicing of serialized data)
- `icon_grid_manager`: reading of grid file
- `fortran_interface_generation`

- `fortran-serialisation`: Branch containing Fortran serialisation framework, which includes granule parser and serialisation cli `f2ser`, and serialisation integration into `icon_liskov`.

flowchart LR
    subgraph Frontend
    A[serialise.py] -->|f2py + regex| C{{Serialisation Interface}}
    B[Liskov] -->|Start/EndStencil Directives| C
    end
    subgraph Backend
    C --> D[SerialisationGenerator]
    D --> E[CodegenWriter]
    E --> F[F90File]
    end

## CLIs

#### `icon4pygen`

Generate Gridtools C++ code for an icon4py fencil as well as all the associated C++ and Fortran bindings (`.h`, `.f90`, `.hpp`, `.cpp`).

Usage: icon4pygen [OPTIONS] FENCIL [BLOCK_SIZE] [LEVELS_PER_THREAD] [OUTPATH]

  Arguments:     
  
      fencil: may be specified as <module>:<member>, where <module> is
          the dotted name of the containing module and <member> is the name of
          the fencil.

      block_size: refers to the number of threads per block to use in a cuda kernel.

      levels_per_thread: how many k-levels to process per thread.

      outpath: represents a path to the folder in which to write all generated code.

Options:
  --is_global
  --imperative  Use the imperative backend for code generation.
  --help        Show this message and exit.

#### `icon_liskov`

Command line interface for interacting with the ICON-Liskov DSL Preprocessor. Automatically generates and inserts Fortran integration code into ICON source code.

Usage: icon_liskov [OPTIONS] INPUT_FILEPATH OUTPUT_FILEPATH

  Arguments:     
      
      input_filepath: Path to the input file to process.
      
      output_filepath: Path to the output file to generate.

Options:
  -p, --profile      Add nvtx profile statements to stencils.
  -m, --metadatagen  Add metadata header with information about program
                     (requires git).
  --help             Show this message and exit.

### dummy dycore-driver
in `atm_dyn_iconam/src/icon4py/driver`

Usage: dycore_driver.py [OPTIONS] INPUT_PATH

  Run the driver.

  usage: python driver/dycore_driver.py
  ../../tests/ser_icondata/mch_ch_r04b09_dsl/ser_data

  steps: 1. initialize model:

      a) read config

      b) initialize grid

      c) initialize/configure components ie "granules"

      d) setup the time loop

  2. run time loop 3. collect output (not implemented)

Options:
  --run_path TEXT    folder for output
  --n_steps INTEGER  number of time steps to run
  --help             Show this message and exit.

python src/icon4py/driver/dycore_driver.py ../testutils/src/icon4py/testutils/ser_icondata/mch_ch_r04b09_dsl/ser_data --n_steps=2 --run_path=/home/magdalena/temp/icon

model/nh_solve
/diffusion
/advection
/graupel
/common
pyutils/