Experimental techincal documentation for NDSL (#86)

* [unrelated] Fix a couple typos and a broken link

* NDSL: technical documentation

---------

Co-authored-by: Roman Cattaneo <>

README.md

@@ -2,18 +2,18 @@
 # Software Modernization Team: The Code Nebulae
 
 This is the team sandbox repository, storing early PoC, relevant benchmark data, staging `ci` workflows, etc.
-Shortname for the packge is `tcn`.
+Shortname for the package is `tcn`.
 
 🚧 This is a staging/PoC area for code, inherently every code here is unstable. 🚧
 
 Below is a quick summary of the tools/packages present in code. More information is package-level READMEs.
 
 ## `ci`
 
-On-premise CI for the GPU ports of GEOS. Includes validation & benchmark worfklows.
+On-premise CI for the GPU ports of GEOS. Includes validation & benchmark workflows.
 
 Heartbeat insure the workflow to reach Discover is working.
-Validation capacities in the case of GEOS is stricly building & running the GPU-enabled version.
+Validation capacities in the case of GEOS is strictly building & running the GPU-enabled version.
 Validation capacities for physics compares OACC and original Fortran on.
 
 | Validation                    | Status    |
@@ -33,11 +33,11 @@ Collection of scripts to mine GEOS log for relevant timing informations for DSL
 
 ## `py_ftn_interface`
 
-Generator of Python <> Interface based on CFFI as used in GEOS integration of the DSL. To be used as a strating point.
+Generator of Python <> Interface based on CFFI as used in GEOS integration of the DSL. To be used as a starting point.
 
 ## `plots`
 
-Collection of scriupts to plot various outputs of GEOS and DSL.
+Collection of scripts to plot various outputs of GEOS and DSL.
 
 ## Software stack builder (`sw_stack`)
 
@@ -53,4 +53,4 @@ Build with pdoc with:
 pdoc -o ./docs smtn
 ```
 
-Documentation is available on [Github Pages](https://geos-esm.github.io/SMT-Nebulae/SMT-Nebulae.html) and will be build automatically at every `main` commit
+Documentation is available on [Github Pages](https://geos-esm.github.io/SMT-Nebulae) and will be build automatically at every `main` commit

ndsl_documentation/README.md

@@ -0,0 +1,3 @@
+# NDSL documentation
+
+A space to keep early prototype technical documentation for the [NASA/NOAA DSL middleware](https://github.com/NOAA-GFDL/NDSL). This will mostly contain early drafts, prototypes, whitepapers, ... since design decisions should be documented (with the code) in the respective repository (e.g. [NDSL](https://github.com/NOAA-GFDL/NDSL) / [DaCe](https://github.com/spcl/dace) / [GT4Py](https://github.com/GridTools/gt4py/)).

ndsl_documentation/gt4py-dace-bridge/README.md

@@ -0,0 +1,3 @@
+# Improved GT4Py-DaCe bridge
+
+Issue: <https://github.com/GEOS-ESM/NDSL/issues/53>

ndsl_documentation/gt4py-dace-bridge/code-blocks.drawio

@@ -0,0 +1,81 @@
+<mxfile host="app.diagrams.net" modified="2024-09-03T15:23:55.160Z" agent="Mozilla/5.0 (X11; Linux x86_64; rv:129.0) Gecko/20100101 Firefox/129.0" etag="LGh8V0W94z09Tky1XRyW" version="24.3.0" type="device">
+  <diagram name="Seite-1" id="uBIzncXjYzNze9gtcR0E">
+    <mxGraphModel dx="1033" dy="1082" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="k6TCTClMSMkHMvDiaAWe-39" value="" style="shape=ext;double=1;rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="50" y="750" width="720" height="410" as="geometry" />
+        </mxCell>
+        <mxCell id="k6TCTClMSMkHMvDiaAWe-35" value="" style="ellipse;shape=cloud;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="619" y="495" width="176" height="160" as="geometry" />
+        </mxCell>
+        <mxCell id="k6TCTClMSMkHMvDiaAWe-29" value="" style="ellipse;shape=cloud;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="352" y="115" width="176" height="160" as="geometry" />
+        </mxCell>
+        <mxCell id="k6TCTClMSMkHMvDiaAWe-1" value="&lt;div style=&quot;font-size: 20px;&quot;&gt;&lt;font style=&quot;font-size: 20px;&quot;&gt;statement0&lt;/font&gt;&lt;/div&gt;&lt;div style=&quot;font-size: 20px;&quot;&gt;&lt;font style=&quot;font-size: 20px;&quot;&gt;statement1&lt;/font&gt;&lt;/div&gt;&lt;div style=&quot;font-size: 20px;&quot;&gt;&lt;font style=&quot;font-size: 20px;&quot;&gt;&lt;br&gt;&lt;/font&gt;&lt;/div&gt;&lt;div style=&quot;font-size: 20px;&quot;&gt;&lt;font style=&quot;font-size: 20px;&quot;&gt;if condition:&lt;br&gt;&lt;/font&gt;&lt;/div&gt;&lt;div style=&quot;font-size: 20px;&quot;&gt;&lt;font style=&quot;font-size: 20px;&quot;&gt;&amp;nbsp; statement2&lt;/font&gt;&lt;/div&gt;&lt;div style=&quot;font-size: 20px;&quot;&gt;&lt;font style=&quot;font-size: 20px;&quot;&gt;&amp;nbsp; statement3&lt;/font&gt;&lt;/div&gt;&lt;div style=&quot;font-size: 20px;&quot;&gt;&lt;font style=&quot;font-size: 20px;&quot;&gt;&lt;br&gt;&lt;/font&gt;&lt;/div&gt;&lt;div style=&quot;font-size: 20px;&quot;&gt;&lt;font style=&quot;font-size: 20px;&quot;&gt;&amp;nbsp; while condition2:&lt;/font&gt;&lt;/div&gt;&lt;div style=&quot;font-size: 20px;&quot;&gt;&lt;font style=&quot;font-size: 20px;&quot;&gt;&amp;nbsp;&amp;nbsp;&amp;nbsp; statement4&lt;/font&gt;&lt;/div&gt;&lt;div style=&quot;font-size: 20px;&quot;&gt;&lt;font style=&quot;font-size: 20px;&quot;&gt;&amp;nbsp;&amp;nbsp;&amp;nbsp; statement5&lt;/font&gt;&lt;/div&gt;&lt;div style=&quot;font-size: 20px;&quot;&gt;&lt;font style=&quot;font-size: 20px;&quot;&gt;&lt;br&gt;&lt;/font&gt;&lt;/div&gt;&lt;div style=&quot;font-size: 20px;&quot;&gt;&lt;font style=&quot;font-size: 20px;&quot;&gt;&amp;nbsp; statement6&lt;/font&gt;&lt;/div&gt;&lt;div style=&quot;font-size: 20px;&quot;&gt;&lt;font style=&quot;font-size: 20px;&quot;&gt;&amp;nbsp; statement7&lt;/font&gt;&lt;/div&gt;&lt;div style=&quot;font-size: 20px;&quot;&gt;&lt;font style=&quot;font-size: 20px;&quot;&gt;&lt;br&gt;&lt;/font&gt;&lt;/div&gt;&lt;div style=&quot;font-size: 20px;&quot;&gt;&lt;font style=&quot;font-size: 20px;&quot;&gt;&lt;font style=&quot;font-size: 20px;&quot;&gt;statement8&lt;/font&gt;&lt;font style=&quot;font-size: 20px;&quot;&gt;&lt;br&gt;&lt;/font&gt;&lt;/font&gt;&lt;/div&gt;" style="whiteSpace=wrap;html=1;aspect=fixed;fontFamily=Courier Prime;fontSource=https%3A%2F%2Ffonts.googleapis.com%2Fcss%3Ffamily%3DCourier%2BPrime;align=left;verticalAlign=top;fillColor=#dae8fc;strokeColor=#6c8ebf;opacity=80;" vertex="1" parent="1">
+          <mxGeometry x="250" y="331" width="369" height="369" as="geometry" />
+        </mxCell>
+        <mxCell id="k6TCTClMSMkHMvDiaAWe-5" value="" style="whiteSpace=wrap;html=1;aspect=fixed;fillColor=#d5e8d4;strokeColor=#82b366;opacity=50;" vertex="1" parent="1">
+          <mxGeometry x="270" y="430" width="230" height="230" as="geometry" />
+        </mxCell>
+        <mxCell id="k6TCTClMSMkHMvDiaAWe-7" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;opacity=70;" vertex="1" parent="1">
+          <mxGeometry x="300" y="525" width="240" height="65" as="geometry" />
+        </mxCell>
+        <mxCell id="k6TCTClMSMkHMvDiaAWe-13" value="" style="shape=crossbar;whiteSpace=wrap;html=1;rounded=1;direction=south;" vertex="1" parent="1">
+          <mxGeometry x="90" y="331" width="20" height="369" as="geometry" />
+        </mxCell>
+        <mxCell id="k6TCTClMSMkHMvDiaAWe-16" value="" style="shape=crossbar;whiteSpace=wrap;html=1;rounded=1;direction=south;" vertex="1" parent="1">
+          <mxGeometry x="125" y="410" width="20" height="250" as="geometry" />
+        </mxCell>
+        <mxCell id="k6TCTClMSMkHMvDiaAWe-17" value="" style="shape=crossbar;whiteSpace=wrap;html=1;rounded=1;direction=south;" vertex="1" parent="1">
+          <mxGeometry x="150" y="517.5" width="20" height="80" as="geometry" />
+        </mxCell>
+        <mxCell id="k6TCTClMSMkHMvDiaAWe-19" value="HorizontalExecution" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="140" y="331" width="60" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="k6TCTClMSMkHMvDiaAWe-20" value="&lt;div&gt;Condition&lt;/div&gt;" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="145" y="410" width="60" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="k6TCTClMSMkHMvDiaAWe-23" value="&lt;div&gt;Loop&lt;/div&gt;" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="170" y="517.5" width="60" height="30" as="geometry" />
+        </mxCell>
+        <mxCell id="k6TCTClMSMkHMvDiaAWe-24" value="&lt;font style=&quot;font-size: 24px;&quot; data-font-src=&quot;https://fonts.googleapis.com/css?family=Caveat&quot; face=&quot;Caveat&quot;&gt;statements are evaluated in a Tasklet&lt;/font&gt;" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="380" y="130" width="120" height="130" as="geometry" />
+        </mxCell>
+        <mxCell id="k6TCTClMSMkHMvDiaAWe-28" value="" style="curved=1;endArrow=classic;html=1;rounded=0;" edge="1" parent="1" source="k6TCTClMSMkHMvDiaAWe-29" target="k6TCTClMSMkHMvDiaAWe-1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="310" y="190" as="sourcePoint" />
+            <mxPoint x="330" y="180" as="targetPoint" />
+            <Array as="points">
+              <mxPoint x="330" y="230" />
+              <mxPoint x="270" y="300" />
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="k6TCTClMSMkHMvDiaAWe-31" value="" style="ellipse;shape=cloud;whiteSpace=wrap;html=1;" vertex="1" parent="1">
+          <mxGeometry x="540" y="130" width="230" height="180" as="geometry" />
+        </mxCell>
+        <mxCell id="k6TCTClMSMkHMvDiaAWe-32" value="&lt;font style=&quot;font-size: 24px;&quot; face=&quot;Caveat&quot;&gt;Conditions and Loops translate to nested SDFG&lt;/font&gt;&lt;font size=&quot;3&quot;&gt;&lt;br&gt;&lt;/font&gt;" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="598" y="155" width="120" height="130" as="geometry" />
+        </mxCell>
+        <mxCell id="k6TCTClMSMkHMvDiaAWe-33" value="" style="curved=1;endArrow=classic;html=1;rounded=0;exitX=0.55;exitY=0.95;exitDx=0;exitDy=0;exitPerimeter=0;entryX=0.488;entryY=0.241;entryDx=0;entryDy=0;entryPerimeter=0;" edge="1" parent="1" source="k6TCTClMSMkHMvDiaAWe-31" target="k6TCTClMSMkHMvDiaAWe-1">
+          <mxGeometry width="50" height="50" relative="1" as="geometry">
+            <mxPoint x="680" y="430" as="sourcePoint" />
+            <mxPoint x="730" y="380" as="targetPoint" />
+            <Array as="points">
+              <mxPoint x="580" y="370" />
+              <mxPoint x="440" y="380" />
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="k6TCTClMSMkHMvDiaAWe-34" value="&lt;font style=&quot;font-size: 24px;&quot; data-font-src=&quot;https://fonts.googleapis.com/css?family=Caveat&quot; face=&quot;Caveat&quot;&gt;each color denotes one &lt;/font&gt;&lt;font style=&quot;font-size: 18px;&quot; face=&quot;Courier Prime&quot; data-font-src=&quot;https://fonts.googleapis.com/css?family=Courier+Prime&quot;&gt;CodeBlock&lt;/font&gt;&lt;font style=&quot;font-size: 24px;&quot; data-font-src=&quot;https://fonts.googleapis.com/css?family=Caveat&quot; face=&quot;Caveat&quot;&gt;&lt;br&gt;&lt;/font&gt;" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="650" y="510" width="120" height="130" as="geometry" />
+        </mxCell>
+        <mxCell id="k6TCTClMSMkHMvDiaAWe-36" value="&lt;div align=&quot;left&quot;&gt;&lt;font style=&quot;font-size: 16px;&quot;&gt;New things&lt;/font&gt;&lt;/div&gt;&lt;div align=&quot;left&quot;&gt;&lt;font style=&quot;font-size: 14px;&quot;&gt;&lt;br&gt;&lt;/font&gt;&lt;/div&gt;&lt;div align=&quot;left&quot;&gt;&lt;font style=&quot;font-size: 14px;&quot;&gt;&lt;font data-font-src=&quot;https://fonts.googleapis.com/css?family=Courier+Prime&quot; face=&quot;Courier Prime&quot;&gt;oir.CodeBlock&lt;/font&gt; allows to use visitor pattern in daceir_builder. unused in other backends&lt;/font&gt;&lt;/div&gt;&lt;div align=&quot;left&quot;&gt;&lt;font style=&quot;font-size: 14px;&quot;&gt;&lt;font data-font-src=&quot;https://fonts.googleapis.com/css?family=Courier+Prime&quot; face=&quot;Courier Prime&quot;&gt;dcir.Condition&lt;/font&gt; state transitions for conditions (the body is a CodeBlock)&lt;br&gt;&lt;/font&gt;&lt;/div&gt;&lt;div align=&quot;left&quot;&gt;&lt;font style=&quot;font-size: 14px;&quot;&gt;&lt;font data-font-src=&quot;https://fonts.googleapis.com/css?family=Courier+Prime&quot; face=&quot;Courier Prime&quot;&gt;dcir.WhileLoop&lt;/font&gt; state transitions for while loops (the body is a CodeBlock)&lt;br&gt;&lt;/font&gt;&lt;/div&gt;&lt;div align=&quot;left&quot;&gt;&lt;font style=&quot;font-size: 14px;&quot;&gt;&lt;br&gt;&lt;/font&gt;&lt;/div&gt;&lt;div&gt;&lt;font style=&quot;font-size: 14px;&quot;&gt;&lt;br&gt;&lt;/font&gt;&lt;/div&gt;&lt;div&gt;&lt;font size=&quot;3&quot;&gt;visit_CodeBlock(node: oir.CodeBlock, ...):&lt;/font&gt;&lt;/div&gt;&lt;div&gt;&lt;font size=&quot;3&quot;&gt;&amp;nbsp; - acts as a scope for local declarations&lt;/font&gt;&lt;/div&gt;&lt;div&gt;&lt;font size=&quot;3&quot;&gt;&amp;nbsp; - separates statements from potential nested CodBlocks&lt;/font&gt;&lt;/div&gt;&lt;div&gt;&lt;font size=&quot;3&quot;&gt;&amp;nbsp; - visit statements and potential nested CodeBlocks&lt;/font&gt;&lt;/div&gt;&lt;div&gt;&lt;font size=&quot;3&quot;&gt;&amp;nbsp; - wires output from statements to nested CodeBlocks&lt;/font&gt;&lt;/div&gt;&lt;div&gt;&lt;font size=&quot;3&quot;&gt;&amp;nbsp; - wires output form nested CodeBlocks to statements at the end of the CodeBlock&lt;/font&gt;&lt;/div&gt;&lt;div&gt;&lt;font size=&quot;3&quot;&gt;&lt;br&gt;&lt;/font&gt;&lt;/div&gt;&lt;div&gt;&lt;font size=&quot;3&quot;&gt;Funny thing about this is that there exists gtir.BlockStmt (used for describing if statements).&lt;br&gt;&lt;/font&gt;&lt;/div&gt;&lt;div&gt;&lt;font size=&quot;3&quot;&gt;These block statements are then split into single statements as mentioned in [1] because&lt;br&gt;that works best for numpy&#39;s where clause.&lt;br&gt;&lt;br&gt;[1] https://gridtools.github.io/gt4py/latest/lang_design.html#conditionals&lt;br&gt;&lt;/font&gt;&lt;/div&gt;" style="text;html=1;align=left;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="80" y="760" width="680" height="370" as="geometry" />
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>