compiler: add top description to generated file

Author: mloubout

devito/ir/cgen/printer.py

@@ -344,7 +344,7 @@ def _print_ListInitializer(self, expr):
         return f"{{{', '.join(self._print(i) for i in expr.params)}}}"
 
     def _print_IndexedPointer(self, expr):
-        return f"{expr.base}{''.join(f'[{self._print(i)}]' for i in expr.index)}"
+        return f"({expr.base}){''.join(f'[{self._print(i)}]' for i in expr.index)}"
 
     def _print_IntDiv(self, expr):
         lhs = self._print(expr.lhs)

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/mpi/overview.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",