---
# System prepended metadata

title: '[Greenline] Python bindings on Turbulence granule'
tags: [cycle28 04/25]

---

# [Greenline] Python bindings on Turbulence granule

<!-- Add the tag for the current cycle number in the top bar -->

- Shaped by: Yilu Chen, Christos Kotsalos, Chia Rui
- Appetite (FTEs, weeks):
- Developers: Yilu, Christos<!-- Filled in at the betting table unless someone is specifically required here -->

## Problem
<!-- The raw idea, a use case, or something we’ve seen that motivates us to work on this -->
We would like to call the 1D turbulence granule from icon-exclaim in icon4py with Python binding and verify the turbulence scheme with serialize data 

## Appetite
<!-- Explain how much time we want to spend and how that constrains the solution -->

## Solution  
<!-- The core elements we came up with, presented in a form that’s easy for people to immediately understand -->

1. **Generate Python bindings with [f2py]**  
   - Create wrappers for `[turbdiff_setup_config]` and `[turbdiff_run]`, since `[f2py]` does not directly support `pointer` or `target` attributes.  

2. **Compile the wrapper with f2py to generate the `turbdiff_f2py` module**  
   - This module can be imported directly into `icon4py`.

3. **Verify turbulence scheme in `icon4py` using serialized test data**

4. **Create the interface for running the turbulence in `icon4py`**


### Details

1. **Generate Python bindings with [f2py]**  
   - Direct usage of `f2py` on the original granule routines (`turbdiff_setup_config` and `turbdiff_run`) is not feasible because they use `pointer` and `target` attributes, which are not directly supported by `f2py`. To work around this, we’ll expose those pointer arguments as regular NumPy arrays in the wrapper interface. These arrays can then be easily converted to GT4Py fields and internally associated with Fortran pointers within the wrapper.
   - combine the wrapper for `turbdiff_setup_config` and `turbdiff_run` into one wrapper. 

2. **Build the Python module using `f2py`**  
   - With the wrapper Fortran code in place, we use `f2py` to compile and generate a Python extension module (e.g., `turbdiff_f2py`).
     ```
     import import turbdiff_f2py as td
     ```
   - This module provides Python-callable interfaces to the Fortran logic and handles the conversion between NumPy arrays and Fortran arrays under the hood.

3. **Verify functionality with serialized data in `icon4py`**  
    - we do not need to generate the serialize data again, it has been generated and stored for the Fortran verification
    - read in the serialize data under the savepoint `icon-turbulence-verify-entry` as the input
    - compare the output with the data under the savepoint `icon-turbulence-verify-turbdiff-exit`

4. **Expose the interface for use in `icon4py`**  (If time permits)
   - port the turbdiff interface


[Notes](https://drive.google.com/file/d/1_fR4SM-_vduKMKAwOygPCtMhWn6dPhIK/view?usp=sharing)

## Rabbit holes
<!-- Details about the solution worth calling out to avoid problems -->

## No-gos
<!-- Anything specifically excluded from the concept: functionality or use cases we intentionally aren’t covering to fit the ## appetite or make the problem tractable -->

## Progress
<!-- Don't fill during shaping. This area is for collecting TODOs during building. As first task during building add a preliminary list of coarse-grained tasks for the project and refine them with finer-grained items when it makes sense as you work on them. -->

- [ ] Task 1 
    - [ ] Subtask A
    - [ ] Subtask X
- [ ] Task 2
    - [ ] Subtask H
    - [ ] Subtask J
- [ ] Discovered Task 3
    - [ ] Subtask L
    - [ ] Subtask S


