Merge pull request #2652 from devitocodes/top-comment

compiler: add top description to generated file

Author: mloubout

devito/ir/iet/visitors.py

@@ -671,6 +671,17 @@ def visit_KernelLaunch(self, o):
         return c.Statement(f'{o.name}{templates}<<<{launch_config}>>>({arguments})')
 
     # Operator-handle machinery
+    def _operator_description(self, o):
+        """
+        Generate cgen description from an iterable of symbols and expressions.
+        """
+        if o.description:
+            if isinstance(o.description, str):
+                return [c.Comment(o.description), blankline]
+            elif isinstance(o.description, Iterable):
+                return [c.MultilineComment(o.description), blankline]
+        else:
+            return [c.Comment("Devito generated operator"), blankline]
 
     def _operator_includes(self, o):
         """
@@ -752,6 +763,9 @@ def visit_Operator(self, o, mode='all'):
             esigns.append(self._gen_signature(i, is_declaration=True))
             efuncs.extend([self._visit(i), blankline])
 
+        # Top description
+        description = self._operator_description(o)
+
         # Definitions
         headers = self._operator_headers(o)
 
@@ -772,8 +786,8 @@ def visit_Operator(self, o, mode='all'):
         if globs:
             globs.append(blankline)
 
-        return c.Module(headers + includes + namespaces + typedecls + globs +
-                        esigns + [blankline, kernel] + efuncs)
+        return c.Module(description + headers + includes + namespaces + typedecls
+                        + globs + esigns + [blankline, kernel] + efuncs)
 
 
 class CInterface(CGen):

devito/operator/operator.py

@@ -768,6 +768,10 @@ def _soname(self):
     def _printer(self):
         return self._Target.Printer
 
+    @cached_property
+    def description(self):
+        return f"Devito generated code for Operator `{self.name}`"
+
     @cached_property
     def headers(self):
         return OrderedSet(*self._printer._headers).union(self._headers)

examples/cfd/01_convection.ipynb

@@ -93,6 +93,8 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
+      "/* Devito generated code for Operator `Kernel` */\n",
+      "\n",
       "#define _POSIX_C_SOURCE 200809L\n",
       "#define START(S) struct timeval start_ ## S , end_ ## S ; gettimeofday(&start_ ## S , NULL);\n",
       "#define STOP(S,T) gettimeofday(&end_ ## S, NULL); T->S += (double)(end_ ## S .tv_sec-start_ ## S.tv_sec)+(double)(end_ ## S .tv_usec-start_ ## S .tv_usec)/1000000;\n",
@@ -323,6 +325,8 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
+      "/* Devito generated code for Operator `Kernel` */\n",
+      "\n",
       "#define _POSIX_C_SOURCE 200809L\n",
       "#define START(S) struct timeval start_ ## S , end_ ## S ; gettimeofday(&start_ ## S , NULL);\n",
       "#define STOP(S,T) gettimeofday(&end_ ## S, NULL); T->S += (double)(end_ ## S .tv_sec-start_ ## S.tv_sec)+(double)(end_ ## S .tv_usec-start_ ## S .tv_usec)/1000000;\n",
@@ -442,6 +446,8 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
+      "/* Devito generated code for Operator `Kernel` */\n",
+      "\n",
       "#define _POSIX_C_SOURCE 200809L\n",
       "#define START(S) struct timeval start_ ## S , end_ ## S ; gettimeofday(&start_ ## S , NULL);\n",
       "#define STOP(S,T) gettimeofday(&end_ ## S, NULL); T->S += (double)(end_ ## S .tv_sec-start_ ## S.tv_sec)+(double)(end_ ## S .tv_usec-start_ ## S .tv_usec)/1000000;\n",
@@ -568,7 +574,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.8"
+   "version": "3.13.5"
   }
  },
  "nbformat": 4,

examples/cfd/01_convection_revisited.ipynb

@@ -124,6 +124,8 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
+      "/* Devito generated code for Operator `Kernel` */\n",
+      "\n",
       "#define _POSIX_C_SOURCE 200809L\n",
       "#define START(S) struct timeval start_ ## S , end_ ## S ; gettimeofday(&start_ ## S , NULL);\n",
       "#define STOP(S,T) gettimeofday(&end_ ## S, NULL); T->S += (double)(end_ ## S .tv_sec-start_ ## S.tv_sec)+(double)(end_ ## S .tv_usec-start_ ## S .tv_usec)/1000000;\n",
@@ -475,7 +477,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.9"
+   "version": "3.13.5"
   }
  },
  "nbformat": 4,

examples/compiler/01_data_regions.ipynb

@@ -314,7 +314,9 @@
     {
      "data": {
       "text/plain": [
-       "[stdout:0] #define _POSIX_C_SOURCE 200809L\n",
+       "[stdout:0] /* Devito generated code for Operator `Kernel` */\n",
+       "\n",
+       "#define _POSIX_C_SOURCE 200809L\n",
        "#define START(S) struct timeval start_ ## S , end_ ## S ; gettimeofday(&start_ ## S , NULL);\n",
        "#define STOP(S,T) gettimeofday(&end_ ## S, NULL); T->S += (double)(end_ ## S .tv_sec-start_ ## S.tv_sec)+(double)(end_ ## S .tv_usec-start_ ## S .tv_usec)/1000000;\n",
        "\n",
@@ -407,7 +409,9 @@
     {
      "data": {
       "text/plain": [
-       "[stdout:0] #define _POSIX_C_SOURCE 200809L\n",
+       "[stdout:0] /* Devito generated code for Operator `Kernel` */\n",
+       "\n",
+       "#define _POSIX_C_SOURCE 200809L\n",
        "#define START(S) struct timeval start_ ## S , end_ ## S ; gettimeofday(&start_ ## S , NULL);\n",
        "#define STOP(S,T) gettimeofday(&end_ ## S, NULL); T->S += (double)(end_ ## S .tv_sec-start_ ## S.tv_sec)+(double)(end_ ## S .tv_usec-start_ ## S .tv_usec)/1000000;\n",
        "\n",

examples/compiler/03_iet-A.ipynb

@@ -563,7 +563,7 @@
      "text": [
       "--- \n",
       "+++ \n",
-      "@@ -43,7 +43,8 @@\n",
+      "@@ -45,7 +45,8 @@\n",
       "         {\n",
       "           for (int z = z_m; z <= z_M; z += 1)\n",
       "           {\n",
@@ -600,7 +600,7 @@
      "text": [
       "--- \n",
       "+++ \n",
-      "@@ -44,7 +44,7 @@\n",
+      "@@ -46,7 +46,7 @@\n",
       "           for (int z = z_m; z <= z_M; z += 1)\n",
       "           {\n",
       "             float r0 = 1.0F/h_y;\n",
@@ -636,7 +636,7 @@
      "text": [
       "--- \n",
       "+++ \n",
-      "@@ -44,7 +44,7 @@\n",
+      "@@ -46,7 +46,7 @@\n",
       "           for (int z = z_m; z <= z_M; z += 1)\n",
       "           {\n",
       "             float r0 = 1.0F/h_y;\n",
@@ -1155,6 +1155,8 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
+      "/* Devito generated code for Operator `Kernel` */\n",
+      "\n",
       "#define _POSIX_C_SOURCE 200809L\n",
       "#define START(S) struct timeval start_ ## S , end_ ## S ; gettimeofday(&start_ ## S , NULL);\n",
       "#define STOP(S,T) gettimeofday(&end_ ## S, NULL); T->S += (double)(end_ ## S .tv_sec-start_ ## S.tv_sec)+(double)(end_ ## S .tv_usec-start_ ## S .tv_usec)/1000000;\n",
@@ -1445,6 +1447,8 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
+      "/* Devito generated code for Operator `Kernel` */\n",
+      "\n",
       "#define _POSIX_C_SOURCE 200809L\n",
       "#define START(S) struct timeval start_ ## S , end_ ## S ; gettimeofday(&start_ ## S , NULL);\n",
       "#define STOP(S,T) gettimeofday(&end_ ## S, NULL); T->S += (double)(end_ ## S .tv_sec-start_ ## S.tv_sec)+(double)(end_ ## S .tv_usec-start_ ## S .tv_usec)/1000000;\n",
@@ -1585,6 +1589,8 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
+      "/* Devito generated code for Operator `Kernel` */\n",
+      "\n",
       "#define _POSIX_C_SOURCE 200809L\n",
       "#define START(S) struct timeval start_ ## S , end_ ## S ; gettimeofday(&start_ ## S , NULL);\n",
       "#define STOP(S,T) gettimeofday(&end_ ## S, NULL); T->S += (double)(end_ ## S .tv_sec-start_ ## S.tv_sec)+(double)(end_ ## S .tv_usec-start_ ## S .tv_usec)/1000000;\n",
@@ -1748,7 +1754,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.8"
+   "version": "3.13.5"
   }
  },
  "nbformat": 4,