Porting the example illustrating Polly from HTML to reStructuredText

[singam-sanjay]

Summary

http://polly.llvm.org/example_manual_matmul.html which illustrates individual passes of Polly, has been ported to reStructuredText and necessary changes have been made to the configuration files used by SPHINX to include the new source as a part of the documentation.

[grosser]

Also, could you update www/experiments/matmul/runall.sh accordingly?

docs/HowToManuallyUseTheIndividualPiecesOfPolly.rst

2

individual (lowercase)

10

Please use maximal 80 characters / column.

14

ONE file

33

ARE detected

36

I see here trailing whitespaces in my patch.

79

Can we drop the space between "main_" and "," (and init_array_ and ",")

87

These links do (still) not work for me? Did you test these? Do they work for you? Or did I muss something on my side? I pulled your patch with 'arc patch D25163', run ninja docs-polly-html and opened the resulting file './tools/polly/docs/html/index.html' in the browser. The command 'find . -name scops.main.dot.png' does not show any file such file in the build directory,

[singam-sanjay]

1. Limited text to 80 columns wherever possible
2. Corrected Grammatical Errors
3. Links to pictures that visualise scops now work

[grosser]

Hi,

thanks for the update. The latest patch is only relative to your previous patch. Could you instead make it relative to a Polly revision (at best trunk)?

Best,
Tobias

[singam-sanjay]

Updated SCoP images and LLVM-IR files

[grosser]

Hi,

thanks for the update. It seems my last comment is still open

The latest patch is only relative to your previous patch. Could you instead make it relative to a Polly revision (at best trunk)?

Could you possibly address this, as it prevents me from testing this?

Best,
Tobias

[singam-sanjay]

The latest diff file was made after rebasing the local branch to commit dbc5521ef947c4b16cb1993e11a2517f5937e028.
Here's a screenshot of git log

docs/HowToManuallyUseTheIndividualPiecesOfPolly.rst

10

Cannot be done on command output.

36

After console ?

79

I've also removed the spaces between *-scopsonly and , in the next line.

But wouldn't the space make the text more readable ?

87

The links now point to pictures from polly.llvm.org website. In the future we might have to have the links point within the repository, i.e. just "experiments/matmul/..." instead of "http://polly.llvm.org/experiments/matmul/..." .

[singam-sanjay]

Ported the matmul example that illustrates Polly to SPHINX.

Also includes Updated SCoP images and LLVM-IR files.

Note : The hyperlinks to SCoP images point to files on the polly.llvm.org website.

[grosser]

Hi Sanyam,

this now already looks very good. Two things that surprised me:

1. I cannot apply this patch with 'arc patch D25163' but get error messages that some files are outdated. I can commit this patch without phabricator, but as we might be working together for a longer time, it would be helpful if you could figure out what is wrong. Can you try to checkout this patch with arcanist yourself?

2. The indentation is inconsistent. In some sections the text is aligned to the section headers / in others it is indented.

[grosser]

Just mark this patch as still requesting some minor changes.

[singam-sanjay]

Hello Dr Grosser,

I've made the indentation consistent.

arc patch D25163 is failing for me too, with errors stating that patch applied to a different version of a file and not its current state.

This is a bit suprising given that I was able to fast-forward my branch without conflicts.

Fortunately, the errors are not due to files that are essential to the change in documentation. The errors are with intermediate .ll files generated while applying different optimisations and .png files that visualise SCoPs. The contents of these files have changed with developments in Polly. Since these are intermediate files, would it be OK to not include updates to these files and remove them from being tracked by git ?

Thank You,
Sanjay Srivallabh

[grosser]

Hi Sanjay,

thanks a lot for the update. We could possibly apply this patch working around this problem, but as we will be working together for a while, I think it would be really good to understand the problem as it will otherwise consistently slow us down in the future. Could you maybe try for an hour to fix it? If you find a solution -- great. If not, we will work around it.

(Also, don't feel worried that the first patch takes very long to get integrated. The main reason is that we spend a lot of time aligning our processes. Generally, after the first couple of patches, patch review is pretty fast.)

Best,
Tobias

[singam-sanjay]

Hello Dr Grosser,

I wasn't able to make much headway into the cause of the problem. Do you have any suggestions ?

Thank You,
Sanjay Srivallabh

[grosser]

Call me Tobias.

Did you try to see why this patch submission did not work? Just post the steps that you have taken, such that others can see what was tried. I will then commit the patch manually.

[singam-sanjay]

Hello Tobias,

I assume you meant uploading the output of git format-patch as submitting the patch, which did work.

As for trying apply this patch, I cloned a fresh repository from http://llvm.org/git/polly.git and applied patch through "arc patch D25163", after issuing the API Token associated with my account through "arc install-certificate".

[grosser]

Hi Sanyam,

if you cannot fix this problem I can just commit the patch manually. For this, please upload your latest patch with fixed indentation (this was not yet uploaded).

Best,
Tobias

[grosser]

Hi Sanjam,

can you update the patch please, that I can commit it.

[singam-sanjay]

Updated runall.sh to suite new command examples.

[grosser]

Hi Sanjay,

did you also fix the indentation that I talked about a couple before. I cannot see this in the diff.

[singam-sanjay]

Hello Tobias,

I've fixed the indentation.

[grosser]

Thank you, I committed these changes!

[singam-sanjay]

Thank You ! This was a wonderful learning experience.

docs/HowToManuallyUseTheIndividualPiecesOfPolly.rst

+==================================================
+How to manually use the Individual pieces of Polly
+==================================================
+
+Execute the individual Polly passes manually
+============================================
+
+.. sectionauthor:: Singapuram Sanjay Srivallabh
+
+This example presents the individual passes that are involved when optimizing code with Polly. We show how to execute them individually and explain for each which analysis is performed or what transformation is applied. In this example the polyhedral transformation is user-provided to show how much performance improvement can be expected by an optimal automatic optimizer.
+
+1. **Create LLVM-IR from the C code**
+-------------------------------------
+        Polly works on LLVM-IR. Hence it is necessary to translate the source files into LLVM-IR. If more than on file should be optimized the files can be combined into a single file with llvm-link.
+        
+        .. code-block:: console
+        
+                clang -S -emit-llvm matmul.c -o matmul.s
+
+
+2. **Prepare the LLVM-IR for Polly**
+------------------------------------
+
+        Polly is only able to work with code that matches a canonical form. To translate the LLVM-IR into this form we use a set of canonicalication passes. They are scheduled by using '-polly-canonicalize'.
+
+        .. code-block:: console
+
+                opt -S -polly-canonicalize matmul.s > matmul.preopt.ll
+
+3. **Show the SCoPs detected by Polly (optional)**
+--------------------------------------------------
+
+        To understand if Polly was able to detect SCoPs, we print the structure of the detected SCoPs. In our example two SCoPs were detected. One in 'init_array' the other in 'main'.
+
+        .. code-block:: console
+
+                $ opt -polly-ast -analyze -q matmul.preopt.ll -polly-process-unprofitable
+
+        .. code-block:: guess
+
+                :: isl ast :: init_array :: %for.cond1.preheader---%for.end19
+
+                if (1)
+
+                    for (int c0 = 0; c0 <= 1535; c0 += 1)
+                      for (int c1 = 0; c1 <= 1535; c1 += 1)
+                        Stmt_for_body3(c0, c1);
+
+                else
+                    {  /* original code */ }
+
+                :: isl ast :: main :: %for.cond1.preheader---%for.end30
+
+                if (1)
+
+                    for (int c0 = 0; c0 <= 1535; c0 += 1)
+                      for (int c1 = 0; c1 <= 1535; c1 += 1) {
+                        Stmt_for_body3(c0, c1);
+                        for (int c2 = 0; c2 <= 1535; c2 += 1)
+                          Stmt_for_body8(c0, c1, c2);
+                      }
+
+                else
+                    {  /* original code */ }
+
+4. **Highlight the detected SCoPs in the CFGs of the program (requires graphviz/dotty)**
+----------------------------------------------------------------------------------------
+
+        Polly can use graphviz to graphically show a CFG in which the detected SCoPs are highlighted. It can also create '.dot' files that can be translated by the 'dot' utility into various graphic formats.
+
+
+        .. code-block:: console
+
+                $ opt -view-scops -disable-output matmul.preopt.ll
+                $ opt -view-scops-only -disable-output matmul.preopt.ll
+
+        The output for the different functions:
+
+        - view-scops : main_ , init_array_ , print_array_
+        - view-scops-only : main-scopsonly_ , init_array-scopsonly_ , print_array-scopsonly_
+
+.. _main:  experiments/matmul/scops.main.dot.png
+.. _init_array: experiments/matmul/scops.init_array.dot.png
+.. _print_array: experiments/matmul/scops.print_array.dot.png
+.. _main-scopsonly: experiments/matmul/scopsonly.main.dot.png
+.. _init_array-scopsonly: experiments/matmul/scopsonly.init_array.dot.png
+.. _print_array-scopsonly: experiments/matmul/scopsonly.print_array.dot.png
+
+5. **View the polyhedral representation of the SCoPs**
+------------------------------------------------------
+
+        .. code-block:: console
+
+                $ opt -polly-scops -analyze matmul.preopt.ll -polly-process-unprofitable
+
+        .. code-block:: guess
+
+                [...]Printing analysis 'Polly - Create polyhedral description of Scops' for region: 'for.cond1.preheader => for.end19' in function 'init_array':
+                    Function: init_array
+                    Region: %for.cond1.preheader---%for.end19
+                    Max Loop Depth:  2
+                        Invariant Accesses: {
+                        }
+                        Context:
+                        {  :  }
+                        Assumed Context:
+                        {  :  }
+                        Invalid Context:
+                        {  : 1 = 0 }
+                        Arrays {
+                            float MemRef_A[*][1536]; // Element size 4
+                            float MemRef_B[*][1536]; // Element size 4
+                        }
+                        Arrays (Bounds as pw_affs) {
+                            float MemRef_A[*][ { [] -> [(1536)] } ]; // Element size 4
+                            float MemRef_B[*][ { [] -> [(1536)] } ]; // Element size 4
+                        }
+                        Alias Groups (0):
+                            n/a
+                        Statements {
+                          Stmt_for_body3
+                                Domain :=
+                                    { Stmt_for_body3[i0, i1] : 0 <= i0 <= 1535 and 0 <= i1 <= 1535 };
+                                Schedule :=
+                                    { Stmt_for_body3[i0, i1] -> [i0, i1] };
+                                MustWriteAccess :=  [Reduction Type: NONE] [Scalar: 0]
+                                    { Stmt_for_body3[i0, i1] -> MemRef_A[i0, i1] };
+                                MustWriteAccess :=  [Reduction Type: NONE] [Scalar: 0]
+                                    { Stmt_for_body3[i0, i1] -> MemRef_B[i0, i1] };
+                        }
+                [...]Printing analysis 'Polly - Create polyhedral description of Scops' for region: 'for.cond1.preheader => for.end30' in function 'main':
+                    Function: main
+                    Region: %for.cond1.preheader---%for.end30
+                    Max Loop Depth:  3
+                    Invariant Accesses: {
+                    }
+                    Context:
+                    {  :  }
+                    Assumed Context:
+                    {  :  }
+                    Invalid Context:
+                    {  : 1 = 0 }
+                    Arrays {
+                        float MemRef_C[*][1536]; // Element size 4
+                        float MemRef_A[*][1536]; // Element size 4
+                        float MemRef_B[*][1536]; // Element size 4
+                    }
+                    Arrays (Bounds as pw_affs) {
+                        float MemRef_C[*][ { [] -> [(1536)] } ]; // Element size 4
+                        float MemRef_A[*][ { [] -> [(1536)] } ]; // Element size 4
+                        float MemRef_B[*][ { [] -> [(1536)] } ]; // Element size 4
+                    }
+                    Alias Groups (0):
+                        n/a
+                    Statements {
+                      Stmt_for_body3
+                            Domain :=
+                                { Stmt_for_body3[i0, i1] : 0 <= i0 <= 1535 and 0 <= i1 <= 1535 };
+                            Schedule :=
+                                { Stmt_for_body3[i0, i1] -> [i0, i1, 0, 0] };
+                            MustWriteAccess :=  [Reduction Type: NONE] [Scalar: 0]
+                                { Stmt_for_body3[i0, i1] -> MemRef_C[i0, i1] };
+                      Stmt_for_body8
+                            Domain :=
+                                { Stmt_for_body8[i0, i1, i2] : 0 <= i0 <= 1535 and 0 <= i1 <= 1535 and 0 <= i2 <= 1535 };
+                            Schedule :=
+                                { Stmt_for_body8[i0, i1, i2] -> [i0, i1, 1, i2] };
+                            ReadAccess := [Reduction Type: NONE] [Scalar: 0]
+                                { Stmt_for_body8[i0, i1, i2] -> MemRef_C[i0, i1] };
+                            ReadAccess := [Reduction Type: NONE] [Scalar: 0]
+                                { Stmt_for_body8[i0, i1, i2] -> MemRef_A[i0, i2] };
+                            ReadAccess := [Reduction Type: NONE] [Scalar: 0]
+                                { Stmt_for_body8[i0, i1, i2] -> MemRef_B[i2, i1] };
+                            MustWriteAccess :=  [Reduction Type: NONE] [Scalar: 0]
+                                { Stmt_for_body8[i0, i1, i2] -> MemRef_C[i0, i1] };
+                    }
+
+                
+6. **Show the dependences for the SCoPs**
+-----------------------------------------
+
+.. code-block:: console
+
+  $ opt -polly-dependences -analyze matmul.preopt.ll -polly-process-unprofitable
+
+.. code-block:: guess
+
+  [...]Printing analysis 'Polly - Calculate dependences' for region: 'for.cond1.preheader => for.end19' in function 'init_array':
+    RAW dependences:
+      {  }
+    WAR dependences:
+      {  }
+    WAW dependences:
+      {  }
+    Reduction dependences:
+      n/a
+    Transitive closure of reduction dependences:
+      {  }
+  [...]Printing analysis 'Polly - Calculate dependences' for region: 'for.cond1.preheader => for.end30' in function 'main':
+    RAW dependences:
+      { Stmt_for_body3[i0, i1] -> Stmt_for_body8[i0, i1, 0] : 0 <= i0 <= 1535 and 0 <= i1 <= 1535; Stmt_for_body8[i0, i1, i2] -> Stmt_for_body8[i0, i1, 1 + i2] : 0 <= i0 <= 1535 and 0 <= i1 <= 1535 and 0 <= i2 <= 1534 }
+    WAR dependences:
+      {  }
+    WAW dependences:
+      { Stmt_for_body3[i0, i1] -> Stmt_for_body8[i0, i1, 0] : 0 <= i0 <= 1535 and 0 <= i1 <= 1535; Stmt_for_body8[i0, i1, i2] -> Stmt_for_body8[i0, i1, 1 + i2] : 0 <= i0 <= 1535 and 0 <= i1 <= 1535 and 0 <= i2 <= 1534 }
+    Reduction dependences:
+      n/a
+    Transitive closure of reduction dependences:
+      {  }
+
+7. **Export jscop files**
+-------------------------
+
+.. code-block:: console
+
+  $ opt -polly-export-jscop matmul.preopt.ll -polly-process-unprofitable
+
+.. code-block:: guess
+
+  [...]Writing JScop '%for.cond1.preheader---%for.end19' in function 'init_array' to './init_array___%for.cond1.preheader---%for.end19.jscop'.
+
+  Writing JScop '%for.cond1.preheader---%for.end30' in function 'main' to './main___%for.cond1.preheader---%for.end30.jscop'.
+
+
+
+8. **Import the changed jscop files and print the updated SCoP structure (optional)**
+-------------------------------------------------------------------------------------
+
+  Polly can reimport jscop files, in which the schedules of the statements are changed. These changed schedules are used to descripe transformations. It is possible to import different jscop files by providing the postfix of the jscop file that is imported.
+
+  We apply three different transformations on the SCoP in the main function. The jscop files describing these transformations are hand written (and available in docs/experiments/matmul).
+
+  **No Polly**
+
+  As a baseline we do not call any Polly code generation, but only apply the normal -O3 optimizations.
+
+  .. code-block:: console
+
+    $ opt matmul.preopt.ll -polly-import-jscop -polly-ast -analyze -polly-process-unprofitable
+
+  .. code-block:: c
+
+    [...]
+    :: isl ast :: main :: %for.cond1.preheader---%for.end30
+    
+    if (1)
+    
+        for (int c0 = 0; c0 <= 1535; c0 += 1)
+          for (int c1 = 0; c1 <= 1535; c1 += 1) {
+            Stmt_for_body3(c0, c1);
+            for (int c3 = 0; c3 <= 1535; c3 += 1)
+              Stmt_for_body8(c0, c1, c3);
+          }
+    
+    else
+        {  /* original code */ }
+    [...]
+
+  **Loop Interchange (and Fission to allow the interchange)**
+
+  We split the loops and can now apply an interchange of the loop dimensions that enumerate Stmt_for_body8.
+
+  .. Although I feel (and have created a .jscop) we can avoid splitting the loops.
+
+  .. code-block:: console
+
+    $ opt matmul.preopt.ll -polly-import-jscop -polly-import-jscop-postfix=interchanged -polly-ast -analyze -polly-process-unprofitable
+
+  .. code-block:: c
+
+    [...]
+    :: isl ast :: main :: %for.cond1.preheader---%for.end30
+
+    if (1)
+
+        {
+          for (int c1 = 0; c1 <= 1535; c1 += 1)
+            for (int c2 = 0; c2 <= 1535; c2 += 1)
+              Stmt_for_body3(c1, c2);
+          for (int c1 = 0; c1 <= 1535; c1 += 1)
+            for (int c2 = 0; c2 <= 1535; c2 += 1)
+              for (int c3 = 0; c3 <= 1535; c3 += 1)
+                Stmt_for_body8(c1, c3, c2);
+        }
+
+    else
+        {  /* original code */ }
+    [...]
+
+  **Interchange + Tiling**
+
+  In addition to the interchange we now tile the second loop nest.
+
+  .. code-block:: console
+
+    $ opt matmul.preopt.ll -polly-import-jscop -polly-import-jscop-postfix=interchanged+tiled -polly-ast -analyze -polly-process-unprofitable
+
+  .. code-block:: c
+
+    [...]
+    :: isl ast :: main :: %for.cond1.preheader---%for.end30
+
+    if (1)
+
+        {
+          for (int c1 = 0; c1 <= 1535; c1 += 1)
+            for (int c2 = 0; c2 <= 1535; c2 += 1)
+              Stmt_for_body3(c1, c2);
+          for (int c1 = 0; c1 <= 1535; c1 += 64)
+            for (int c2 = 0; c2 <= 1535; c2 += 64)
+              for (int c3 = 0; c3 <= 1535; c3 += 64)
+                for (int c4 = c1; c4 <= c1 + 63; c4 += 1)
+                  for (int c5 = c3; c5 <= c3 + 63; c5 += 1)
+                    for (int c6 = c2; c6 <= c2 + 63; c6 += 1)
+                      Stmt_for_body8(c4, c6, c5);
+        }
+
+    else
+        {  /* original code */ }
+    [...]
+
+
+  **Interchange + Tiling + Strip-mining to prepare vectorization**
+
+  To later allow vectorization we create a so called trivially parallelizable loop. It is innermost, parallel and has only four iterations. It can be replaced by 4-element SIMD instructions.
+
+  .. code-block:: console
+
+    $ opt matmul.preopt.ll -polly-import-jscop -polly-import-jscop-postfix=interchanged+tiled -polly-ast -analyze -polly-process-unprofitable
+
+  .. code-block:: c
+
+    [...]
+    :: isl ast :: main :: %for.cond1.preheader---%for.end30
+
+    if (1)
+
+        {
+          for (int c1 = 0; c1 <= 1535; c1 += 1)
+            for (int c2 = 0; c2 <= 1535; c2 += 1)
+              Stmt_for_body3(c1, c2);
+          for (int c1 = 0; c1 <= 1535; c1 += 64)
+            for (int c2 = 0; c2 <= 1535; c2 += 64)
+              for (int c3 = 0; c3 <= 1535; c3 += 64)
+                for (int c4 = c1; c4 <= c1 + 63; c4 += 1)
+                  for (int c5 = c3; c5 <= c3 + 63; c5 += 1)
+                    for (int c6 = c2; c6 <= c2 + 63; c6 += 4)
+                      for (int c7 = c6; c7 <= c6 + 3; c7 += 1)
+                        Stmt_for_body8(c4, c7, c5);
+        }
+
+    else
+        {  /* original code */ }
+    [...]
+
+9. **Codegenerate the SCoPs**
+-----------------------------
+
+  This generates new code for the SCoPs detected by polly. If -polly-import-jscop is present, transformations specified in the imported jscop files will be applied.
+
+
+  .. code-block:: console
+
+    $ opt matmul.preopt.ll | opt -O3 > matmul.normalopt.ll
+    
+  .. code-block:: console
+
+    $ opt matmul.preopt.ll -polly-import-jscop -polly-import-jscop-postfix=interchanged -polly-codegen -polly-process-unprofitable | opt -O3 > matmul.polly.interchanged.ll
+
+  .. code-block:: guess
+
+    Reading JScop '%for.cond1.preheader---%for.end19' in function 'init_array' from './init_array___%for.cond1.preheader---%for.end19.jscop.interchanged'.
+    File could not be read: No such file or directory
+    Reading JScop '%for.cond1.preheader---%for.end30' in function 'main' from './main___%for.cond1.preheader---%for.end30.jscop.interchanged'.
+
+  .. code-block:: console
+
+    $ opt matmul.preopt.ll -polly-import-jscop -polly-import-jscop-postfix=interchanged+tiled -polly-codegen -polly-process-unprofitable | opt -O3 > matmul.polly.interchanged+tiled.ll
+    
+  .. code-block:: guess
+
+    Reading JScop '%for.cond1.preheader---%for.end19' in function 'init_array' from './init_array___%for.cond1.preheader---%for.end19.jscop.interchanged+tiled'.
+    File could not be read: No such file or directory
+    Reading JScop '%for.cond1.preheader---%for.end30' in function 'main' from './main___%for.cond1.preheader---%for.end30.jscop.interchanged+tiled'.
+
+  .. code-block:: console
+
+    $ opt matmul.preopt.ll -polly-import-jscop -polly-import-jscop-postfix=interchanged+tiled+vector -polly-codegen -polly-vectorizer=polly -polly-process-unprofitable | opt -O3 > matmul.polly.interchanged+tiled+vector.ll
+
+  .. code-block:: guess
+
+    Reading JScop '%for.cond1.preheader---%for.end19' in function 'init_array' from './init_array___%for.cond1.preheader---%for.end19.jscop.interchanged+tiled+vector'.
+    File could not be read: No such file or directory
+    Reading JScop '%for.cond1.preheader---%for.end30' in function 'main' from './main___%for.cond1.preheader---%for.end30.jscop.interchanged+tiled+vector'.
+
+  .. code-block:: console
+
+    $ opt matmul.preopt.ll -polly-import-jscop -polly-import-jscop-postfix=interchanged+tiled+vector -polly-codegen -polly-vectorizer=polly -polly-parallel -polly-process-unprofitable | opt -O3 > matmul.polly.interchanged+tiled+openmp.ll
+
+  .. code-block:: guess
+
+    Reading JScop '%for.cond1.preheader---%for.end19' in function 'init_array' from './init_array___%for.cond1.preheader---%for.end19.jscop.interchanged+tiled+vector'.
+    File could not be read: No such file or directory
+    Reading JScop '%for.cond1.preheader---%for.end30' in function 'main' from './main___%for.cond1.preheader---%for.end30.jscop.interchanged+tiled+vector'.
+ 
+
+10. **Create the executables**
+------------------------------
+
+.. code-block:: console
+
+  $ llc matmul.normalopt.ll -o matmul.normalopt.s && gcc matmul.normalopt.s -o matmul.normalopt.exe
+  $ llc matmul.polly.interchanged.ll -o matmul.polly.interchanged.s && gcc matmul.polly.interchanged.s -o matmul.polly.interchanged.exe
+  $ llc matmul.polly.interchanged+tiled.ll -o matmul.polly.interchanged+tiled.s && gcc matmul.polly.interchanged+tiled.s -o matmul.polly.interchanged+tiled.exe
+  $ llc matmul.polly.interchanged+tiled+vector.ll -o matmul.polly.interchanged+tiled+vector.s && gcc matmul.polly.interchanged+tiled+vector.s -o matmul.polly.interchanged+tiled+vector.exe
+  $ llc matmul.polly.interchanged+tiled+vector+openmp.ll -o matmul.polly.interchanged+tiled+vector+openmp.s && gcc -fopenmp matmul.polly.interchanged+tiled+vector+openmp.s -o matmul.polly.interchanged+tiled+vector+openmp.exe 
+
+11. **Compare the runtime of the executables**
+----------------------------------------------
+
+  By comparing the runtimes of the different code snippets we see that a simple loop interchange gives here the largest performance boost. However in this case, adding vectorization and using OpenMP degrades the performance.
+
+.. code-block:: console
+
+  $ time ./matmul.normalopt.exe
+
+  real  0m11.295s
+  user  0m11.288s
+  sys 0m0.004s
+  $ time ./matmul.polly.interchanged.exe
+
+  real  0m0.988s
+  user  0m0.980s
+  sys 0m0.008s
+  $ time ./matmul.polly.interchanged+tiled.exe
+
+  real  0m0.830s
+  user  0m0.816s
+  sys 0m0.012s
+  $ time ./matmul.polly.interchanged+tiled+vector.exe
+
+  real  0m5.430s
+  user  0m5.424s
+  sys 0m0.004s
+  $ time ./matmul.polly.interchanged+tiled+vector+openmp.exe
+
+  real  0m3.184s
+  user  0m11.972s
+  sys 0m0.036s
+
+

docs/experiments/matmul/init_array___%for.cond1.preheader---%for.end19.jscop

+{
+   "arrays" : [
+      {
+         "name" : "MemRef_A",
+         "sizes" : [ "1536" ],
+         "type" : "float"
+      },
+      {
+         "name" : "MemRef_B",
+         "sizes" : [ "1536" ],
+         "type" : "float"
+      }
+   ],
+   "context" : "{  :  }",
+   "name" : "%for.cond1.preheader---%for.end19",
+   "statements" : [
+      {
+         "accesses" : [
+            {
+               "kind" : "write",
+               "relation" : "{ Stmt_for_body3[i0, i1] -> MemRef_A[i0, i1] }"
+            },
+            {
+               "kind" : "write",
+               "relation" : "{ Stmt_for_body3[i0, i1] -> MemRef_B[i0, i1] }"
+            }
+         ],
+         "domain" : "{ Stmt_for_body3[i0, i1] : 0 <= i0 <= 1535 and 0 <= i1 <= 1535 }",
+         "name" : "Stmt_for_body3",
+         "schedule" : "{ Stmt_for_body3[i0, i1] -> [i0, i1] }"
+      }
+   ]
+}

docs/experiments/matmul/main___%for.cond1.preheader---%for.end30.jscop

+{
+   "arrays" : [
+      {
+         "name" : "MemRef_C",
+         "sizes" : [ "1536" ],
+         "type" : "float"
+      },
+      {
+         "name" : "MemRef_A",
+         "sizes" : [ "1536" ],
+         "type" : "float"
+      },
+      {
+         "name" : "MemRef_B",
+         "sizes" : [ "1536" ],
+         "type" : "float"
+      }
+   ],
+   "context" : "{  :  }",
+   "name" : "%for.cond1.preheader---%for.end30",
+   "statements" : [
+      {
+         "accesses" : [
+            {
+               "kind" : "write",
+               "relation" : "{ Stmt_for_body3[i0, i1] -> MemRef_C[i0, i1] }"
+            }
+         ],
+         "domain" : "{ Stmt_for_body3[i0, i1] : 0 <= i0 <= 1535 and 0 <= i1 <= 1535 }",
+         "name" : "Stmt_for_body3",
+         "schedule" : "{ Stmt_for_body3[i0, i1] -> [i0, i1, 0, 0] }"
+      },
+      {
+         "accesses" : [
+            {
+               "kind" : "read",
+               "relation" : "{ Stmt_for_body8[i0, i1, i2] -> MemRef_C[i0, i1] }"
+            },
+            {
+               "kind" : "read",
+               "relation" : "{ Stmt_for_body8[i0, i1, i2] -> MemRef_A[i0, i2] }"
+            },
+            {
+               "kind" : "read",
+               "relation" : "{ Stmt_for_body8[i0, i1, i2] -> MemRef_B[i2, i1] }"
+            },
+            {
+               "kind" : "write",
+               "relation" : "{ Stmt_for_body8[i0, i1, i2] -> MemRef_C[i0, i1] }"
+            }
+         ],
+         "domain" : "{ Stmt_for_body8[i0, i1, i2] : 0 <= i0 <= 1535 and 0 <= i1 <= 1535 and 0 <= i2 <= 1535 }",
+         "name" : "Stmt_for_body8",
+         "schedule" : "{ Stmt_for_body8[i0, i1, i2] -> [i0, i1, 1, i2] }"
+      }
+   ]
+}

docs/experiments/matmul/main___%for.cond1.preheader---%for.end30.jscop.interchanged

+{
+   "arrays" : [
+      {
+         "name" : "MemRef_C",
+         "sizes" : [ "1536" ],
+         "type" : "float"
+      },
+      {
+         "name" : "MemRef_A",
+         "sizes" : [ "1536" ],
+         "type" : "float"
+      },
+      {
+         "name" : "MemRef_B",
+         "sizes" : [ "1536" ],
+         "type" : "float"
+      }
+   ],
+   "context" : "{  :  }",
+   "name" : "%for.cond1.preheader---%for.end30",
+   "statements" : [
+      {
+         "accesses" : [
+            {
+               "kind" : "write",
+               "relation" : "{ Stmt_for_body3[i0, i1] -> MemRef_C[i0, i1] }"
+            }
+         ],
+         "domain" : "{ Stmt_for_body3[i0, i1] : 0 <= i0 <= 1535 and 0 <= i1 <= 1535 }",
+         "name" : "Stmt_for_body3",
+         "schedule" : "{ Stmt_for_body3[i0, i1] -> [0, i0, i1, 0] }"
+      },
+      {
+         "accesses" : [
+            {
+               "kind" : "read",
+               "relation" : "{ Stmt_for_body8[i0, i1, i2] -> MemRef_C[i0, i1] }"
+            },
+            {
+               "kind" : "read",
+               "relation" : "{ Stmt_for_body8[i0, i1, i2] -> MemRef_A[i0, i2] }"
+            },
+            {
+               "kind" : "read",
+               "relation" : "{ Stmt_for_body8[i0, i1, i2] -> MemRef_B[i2, i1] }"
+            },
+            {
+               "kind" : "write",
+               "relation" : "{ Stmt_for_body8[i0, i1, i2] -> MemRef_C[i0, i1] }"
+            }
+         ],
+         "domain" : "{ Stmt_for_body8[i0, i1, i2] : 0 <= i0 <= 1535 and 0 <= i1 <= 1535 and 0 <= i2 <= 1535 }",
+         "name" : "Stmt_for_body8",
+         "schedule" : "{ Stmt_for_body8[i0, i1, i2] -> [1, i0, i2, i1] }"
+      }
+   ]
+}

docs/experiments/matmul/main___%for.cond1.preheader---%for.end30.jscop.interchanged+tiled

+{
+   "arrays" : [
+      {
+         "name" : "MemRef_C",
+         "sizes" : [ "1536" ],
+         "type" : "float"
+      },
+      {
+         "name" : "MemRef_A",
+         "sizes" : [ "1536" ],
+         "type" : "float"
+      },
+      {
+         "name" : "MemRef_B",
+         "sizes" : [ "1536" ],
+         "type" : "float"
+      }
+   ],
+   "context" : "{  :  }",
+   "name" : "%for.cond1.preheader---%for.end30",
+   "statements" : [
+      {
+         "accesses" : [
+            {
+               "kind" : "write",
+               "relation" : "{ Stmt_for_body3[i0, i1] -> MemRef_C[i0, i1] }"
+            }
+         ],
+         "domain" : "{ Stmt_for_body3[i0, i1] : 0 <= i0 <= 1535 and 0 <= i1 <= 1535 }",
+         "name" : "Stmt_for_body3",
+         "schedule" : "{ Stmt_for_body3[i0, i1] -> [0, i0, i1, 0, 0, 0, 0 ] }"
+      },
+      {
+         "accesses" : [
+            {
+               "kind" : "read",
+               "relation" : "{ Stmt_for_body8[i0, i1, i2] -> MemRef_C[i0, i1] }"
+            },
+            {
+               "kind" : "read",
+               "relation" : "{ Stmt_for_body8[i0, i1, i2] -> MemRef_A[i0, i2] }"
+            },
+            {
+               "kind" : "read",
+               "relation" : "{ Stmt_for_body8[i0, i1, i2] -> MemRef_B[i2, i1] }"
+            },
+            {
+               "kind" : "write",
+               "relation" : "{ Stmt_for_body8[i0, i1, i2] -> MemRef_C[i0, i1] }"
+            }
+         ],
+         "domain" : "{ Stmt_for_body8[i0, i1, i2] : 0 <= i0 <= 1535 and 0 <= i1 <= 1535 and 0 <= i2 <= 1535 }",
+         "name" : "Stmt_for_body8",
+         "schedule" : "{ Stmt_for_body8[i0, i1, i2] -> [1, o0, o1, o2, i0, i2, i1]: o0 <= i0 < o0 + 64 and o1 <= i1 < o1 + 64 and o2 <= i2 < o2 + 64 and o0 % 64 = 0 and o1 % 64 = 0 and o2 % 64 = 0 }"
+      }
+   ]
+}

docs/experiments/matmul/main___%for.cond1.preheader---%for.end30.jscop.interchanged+tiled+vector

+{
+   "arrays" : [
+      {
+         "name" : "MemRef_C",
+         "sizes" : [ "1536" ],
+         "type" : "float"
+      },
+      {
+         "name" : "MemRef_A",
+         "sizes" : [ "1536" ],
+         "type" : "float"
+      },
+      {
+         "name" : "MemRef_B",
+         "sizes" : [ "1536" ],
+         "type" : "float"
+      }
+   ],
+   "context" : "{  :  }",
+   "name" : "%for.cond1.preheader---%for.end30",
+   "statements" : [
+      {
+         "accesses" : [
+            {
+               "kind" : "write",
+               "relation" : "{ Stmt_for_body3[i0, i1] -> MemRef_C[i0, i1] }"
+            }
+         ],
+         "domain" : "{ Stmt_for_body3[i0, i1] : 0 <= i0 <= 1535 and 0 <= i1 <= 1535 }",
+         "name" : "Stmt_for_body3",
+         "schedule" : "{ Stmt_for_body3[i0, i1] -> [0, i0, i1, 0, 0, 0, 0, 0 ] }"
+      },
+      {
+         "accesses" : [
+            {
+               "kind" : "read",
+               "relation" : "{ Stmt_for_body8[i0, i1, i2] -> MemRef_C[i0, i1] }"
+            },
+            {
+               "kind" : "read",
+               "relation" : "{ Stmt_for_body8[i0, i1, i2] -> MemRef_A[i0, i2] }"
+            },
+            {
+               "kind" : "read",
+               "relation" : "{ Stmt_for_body8[i0, i1, i2] -> MemRef_B[i2, i1] }"
+            },
+            {
+               "kind" : "write",
+               "relation" : "{ Stmt_for_body8[i0, i1, i2] -> MemRef_C[i0, i1] }"
+            }
+         ],
+         "domain" : "{ Stmt_for_body8[i0, i1, i2] : 0 <= i0 <= 1535 and 0 <= i1 <= 1535 and 0 <= i2 <= 1535 }",
+         "name" : "Stmt_for_body8",
+         "schedule" : "{ Stmt_for_body8[i0, i1, i2] -> [1, o0, o1, o2, i0, i2, oo1, i1]: o0 <= i0 < o0 + 64 and o1 <= oo1 < o1 + 64 and o2 <= i2 < o2 + 64 and oo1 <= i1 < oo1 + 4 and o0 % 64 = 0 and o1 % 64 = 0 and o2 % 64 = 0 and oo1 % 4 = 0 }"
+      }
+   ]
+}

docs/index.rst

 
    Architecture
    UsingPollyWithClang
+   HowToManuallyUseTheIndividualPiecesOfPolly
 
-* `How to manually use the individual pieces of Polly <http://polly.llvm.org/example_manual_matmul.html>`_
 * `A list of Polly passes <http://polly.llvm.org/documentation/passes.html>`_
 
 Indices and tables

www/experiments/matmul/init_array___%for.cond---%for.end19.jscop

-{
-   "context" : "{  :  }",
-   "name" : "for.cond => for.end19",
-   "statements" : [
-      {
-         "accesses" : [
-            {
-               "kind" : "write",
-               "relation" : "{ Stmt_for_body3[i0, i1] -> MemRef_A[1536i0 + i1] }"
-            },
-            {
-               "kind" : "write",
-               "relation" : "{ Stmt_for_body3[i0, i1] -> MemRef_B[1536i0 + i1] }"
-            }
-         ],
-         "domain" : "{ Stmt_for_body3[i0, i1] : i0 >= 0 and i0 <= 1535 and i1 >= 0 and i1 <= 1535 }",
-         "name" : "Stmt_for_body3",
-         "schedule" : "{ Stmt_for_body3[i0, i1] -> schedule[0, i0, 0, i1, 0] }"
-      }
-   ]
-}

www/experiments/matmul/main___%for.cond---%for.end30.jscop

-{
-   "context" : "{  :  }",
-   "name" : "for.cond => for.end30",
-   "statements" : [
-      {
-         "accesses" : [
-            {
-               "kind" : "write",
-               "relation" : "{ Stmt_for_body3[i0, i1] -> MemRef_C[1536i0 + i1] }"
-            }
-         ],
-         "domain" : "{ Stmt_for_body3[i0, i1] : i0 >= 0 and i0 <= 1535 and i1 >= 0 and i1 <= 1535 }",
-         "name" : "Stmt_for_body3",
-         "schedule" : "{ Stmt_for_body3[i0, i1] -> schedule[0, i0, 0, i1, 0, 0, 0] }"
-      },
-      {
-         "accesses" : [
-            {
-               "kind" : "read",
-               "relation" : "{ Stmt_for_body8[i0, i1, i2] -> MemRef_C[1536i0 + i1] }"
-            },
-            {
-               "kind" : "read",
-               "relation" : "{ Stmt_for_body8[i0, i1, i2] -> MemRef_A[1536i0 + i2] }"
-            },
-            {
-               "kind" : "read",
-               "relation" : "{ Stmt_for_body8[i0, i1, i2] -> MemRef_B[i1 + 1536i2] }"
-            },
-            {
-               "kind" : "write",
-               "relation" : "{ Stmt_for_body8[i0, i1, i2] -> MemRef_C[1536i0 + i1] }"
-            }
-         ],
-         "domain" : "{ Stmt_for_body8[i0, i1, i2] : i0 >= 0 and i0 <= 1535 and i1 >= 0 and i1 <= 1535 and i2 >= 0 and i2 <= 1535 }",
-         "name" : "Stmt_for_body8",
-         "schedule" : "{ Stmt_for_body8[i0, i1, i2] -> schedule[0, i0, 0, i1, 1, i2, 0] }"
-      }
-   ]
-}

www/experiments/matmul/main___%for.cond---%for.end30.jscop.interchanged

-{
-   "context" : "{ [] }",
-   "name" : "%1 => %17",
-   "statements" : [
-      {
-         "accesses" : [
-            {
-               "kind" : "write",
-               "relation" : "{ Stmt_4[i0, i1] -> MemRef_C[1536i0 + i1] }"
-            }
-         ],
-         "domain" : "{ Stmt_4[i0, i1] : i0 >= 0 and i0 <= 1023 and i1 >= 0 and i1 <= 1023 }",
-         "name" : "Stmt_4",
-         "schedule" : "{ Stmt_4[i0, i1] -> schedule[0, i0, 0, i1, 0, 0, 0] }"
-      },
-      {
-         "accesses" : [
-            {
-               "kind" : "read",
-               "relation" : "{ Stmt_6[i0, i1, i2] -> MemRef_C[1536i0 + i1] }"
-            },
-            {
-               "kind" : "read",
-               "relation" : "{ Stmt_6[i0, i1, i2] -> MemRef_A[1536i0 + i2] }"
-            },
-            {
-               "kind" : "read",
-               "relation" : "{ Stmt_6[i0, i1, i2] -> MemRef_B[i1 + 1536i2] }"
-            },
-            {
-               "kind" : "write",
-               "relation" : "{ Stmt_6[i0, i1, i2] -> MemRef_C[1536i0 + i1] }"
-            }
-         ],
-         "domain" : "{ Stmt_6[i0, i1, i2] : i0 >= 0 and i0 <= 1023 and i1 >= 0 and i1 <= 1023 and i2 >= 0 and i2 <= 1023 }",
-         "name" : "Stmt_6",
-         "schedule" : "{ Stmt_6[i0, i1, i2] -> schedule[1, i0, 0, i2, 0, i1, 0] }"
-      }
-   ]
-}

www/experiments/matmul/main___%for.cond---%for.end30.jscop.interchanged+tiled

-{
-   "context" : "{ [] }",
-   "name" : "%1 => %17",
-   "statements" : [
-      {
-         "accesses" : [
-            {
-               "kind" : "write",
-               "relation" : "{ Stmt_4[i0, i1] -> MemRef_C[1536i0 + i1] }"
-            }
-         ],
-         "domain" : "{ Stmt_4[i0, i1] : i0 >= 0 and i0 <= 1023 and i1 >= 0 and i1 <= 1023 }",
-         "name" : "Stmt_4",
-         "schedule" : "{ Stmt_4[i0, i1] -> schedule[0, i0, 0, i1, 0, 0, 0] }"
-      },
-      {
-         "accesses" : [
-            {
-               "kind" : "read",
-               "relation" : "{ Stmt_6[i0, i1, i2] -> MemRef_C[1536i0 + i1] }"
-            },
-            {
-               "kind" : "read",
-               "relation" : "{ Stmt_6[i0, i1, i2] -> MemRef_A[1536i0 + i2] }"
-            },
-            {
-               "kind" : "read",
-               "relation" : "{ Stmt_6[i0, i1, i2] -> MemRef_B[i1 + 1536i2] }"
-            },
-            {
-               "kind" : "write",
-               "relation" : "{ Stmt_6[i0, i1, i2] -> MemRef_C[1536i0 + i1] }"
-            }
-         ],
-         "domain" : "{ Stmt_6[i0, i1, i2] : i0 >= 0 and i0 <= 1023 and i1 >= 0 and i1 <= 1023 and i2 >= 0 and i2 <= 1023 }",
-         "name" : "Stmt_6",
-         "schedule" : "{ Stmt_6[i0, i1, i2] -> schedule[1, o0, o1, o2, i0, i2, i1]: o0 <= i0 < o0 + 64 and o1 <= i1 < o1 + 64 and o2 <= i2 < o2 + 64 and o0 % 64 = 0 and o1 % 64 = 0 and o2 % 64 = 0 }"
-      }
-   ]
-}

www/experiments/matmul/main___%for.cond---%for.end30.jscop.interchanged+tiled+vector

-{
-   "context" : "{ [] }",
-   "name" : "%1 => %17",
-   "statements" : [
-      {
-         "accesses" : [
-            {
-               "kind" : "write",
-               "relation" : "{ Stmt_4[i0, i1] -> MemRef_C[1536i0 + i1] }"
-            }
-         ],
-         "domain" : "{ Stmt_4[i0, i1] : i0 >= 0 and i0 <= 1023 and i1 >= 0 and i1 <= 1023 }",
-         "name" : "Stmt_4",
-         "schedule" : "{ Stmt_4[i0, i1] -> schedule[0, i0, 0, i1, 0, 0, 0, 0] }"
-      },
-      {
-         "accesses" : [
-            {
-               "kind" : "read",
-               "relation" : "{ Stmt_6[i0, i1, i2] -> MemRef_C[1536i0 + i1] }"
-            },
-            {
-               "kind" : "read",
-               "relation" : "{ Stmt_6[i0, i1, i2] -> MemRef_A[1536i0 + i2] }"
-            },
-            {
-               "kind" : "read",
-               "relation" : "{ Stmt_6[i0, i1, i2] -> MemRef_B[i1 + 1536i2] }"
-            },
-            {
-               "kind" : "write",
-               "relation" : "{ Stmt_6[i0, i1, i2] -> MemRef_C[1536i0 + i1] }"
-            }
-         ],
-         "domain" : "{ Stmt_6[i0, i1, i2] : i0 >= 0 and i0 <= 1023 and i1 >= 0 and i1 <= 1023 and i2 >= 0 and i2 <= 1023 }",
-         "name" : "Stmt_6",
-         "schedule" : "{ Stmt_6[i0, i1, i2] -> schedule[1, o0, o1, o2, i0, i2, ii1, i1]: o0 <= i0 < o0 + 64 and o1 <= i1 < o1 + 64 and o2 <= i2 < o2 + 64 and o0 % 64 = 0 and o1 % 64 = 0 and o2 % 64 = 0 and ii1 % 4 = 0 and ii1 <= i1 < ii1 + 4}"
-      }
-   ]
-}