Merge pull request #10 from C2SM-RCM/v0.4.0

v0.4.0

.gitignore

@@ -8,3 +8,6 @@
 *.toc
 
 *.out
+*.bbl
+*.blg
+*.xmod

README.md

@@ -1,24 +1,24 @@
 # CLAW language specification
 
 #### Reference compiler
-The CLAW FORTRAN Compiler is the reference compiler for the claw directive language. The project can be found here: [claw-compiler](https://github.com/C2SM-RCM/claw-compiler)
+The CLAW FORTRAN Compiler is the reference compiler for the claw directive
+language. The project can be found here:
+[claw-compiler](https://github.com/C2SM-RCM/claw-compiler)
 
 #### Versions
 ##### Specification document
-The current specification can be found here: [CLAW specification document](./claw_language_specifications.pdf)
+The current specification can be found here:
+[CLAW specification document](./claw_language_specifications.pdf)
 
 ##### Generating the specification document
 The specification is written using LaTeX. To generate the PDF document, you
 can use `pdflatex` with the following command:
 
 ```
-pdflatex ./documentation/claw_language_specifications.tex
+cd documentation
+pdflatex claw_language_specifications.tex
 ```
 
-##### On going
-Currently designing version 0.3a of the language specification. This work is done
-in the `master` branch.
-
 ##### History
 * **Iteration 0.1**:
   * Define low-level block transformation.
@@ -31,13 +31,16 @@ in the `master` branch.
     * Add loop transformation `loop-hoist`.
     * Add array notation transformation `array-transform`.
     * Add claw transformation `kcache` for column caching.
-    * Add claw transformation `call` for on the fly computation (array acess to
+    * Add claw transformation `call` for on the fly computation (array access to
       function call).
   * Start to abstract low-level transformation.
     * Introduction of the `parallelize` directive with the `define dimension`
       and `forward` clauses
 * **Iteration 0.3**:      
   * Refine previous iterations, especially `parallelize` directive.
+  **Iteration 0.4**:      
+    * Refine previous iterations, especially `parallelize` directive.
+    * Add conditional extraction `if-extract`
 
 #### General information about the CLAW language
 The directives are either local or global.
@@ -59,10 +62,14 @@ This language is separated in the followings sections:
   * loop interchange/reordering
   * loop extraction
   * loop hoisting
-* OpenACC abstractions/helpers
+  * conditional extraction
+* OpenACC/OpenMP abstractions/helpers
   * array notation to do statement  
+  * conditional primitive directive
 * Utilities
   * remove
+  * ignore
+  * verbatim
 
 ##### Line continuation
 CLAW directives can be defined on several line. The syntax is described in the
@@ -80,13 +87,20 @@ loop-interchange can be used together in a group of nested loops.
 
 The interpretation order of the directives is the following:
 
-1. remove
-2. array-transform
-3. loop-extract
-4. loop-fusion
-5. loop-hoist
-6. loop-interchange
-7. formatting transformation (internal transformation only)
+1. ignore
+2. remove
+3. primitive
+4. array-transform
+5. loop-extract
+6. loop-hoist
+7. loop-fusion
+8. loop-interchange
+9. on-the-fly
+10. kcache
+11. if-extract
+11. parallelize
+12. parallelize-forward
+13. formatting transformation (internal transformation only)
 
 Users must be aware that directives transformation are applied sequentially and
 therefore, a transformation can be performed on already transformed code.

documentation/claw_abstract_transformation.tex

@@ -1,19 +1,20 @@
 \subsection{Column model abstraction}
 
 The \lstinline!parallelize! directive is used to parallelize a column based
-algorithm. In weather prediction models, the physical parametrizations are column
-independent problems. This means that the algorithm to compute the different
-output fields, can be defined with as a single do statement iterating over the vertical dimension and there is no horizontal dependency.
-The \lstinline!parallelize! directive is then used to parallelize efficiently this 
-column algorithm over the domain (horizontal 
-dimensions).
-The directive is local to a subroutine. Therefore, as a pre-condition, the column algorithm 
-must be enclosed in a module subroutine.
-
+algorithm. In weather prediction models, the physical parametrizations are
+column independent problems. This means that the algorithm to compute the
+different output fields, can be defined with as a single do statement
+iterating over the vertical dimension and there is no horizontal dependency.
+The \lstinline!parallelize! directive is then used to parallelize efficiently
+this column algorithm over the domain (horizontal dimensions).
+The directive is local to a subroutine. Therefore, as a pre-condition, the
+column algorithm must be enclosed in a module subroutine.
+
+\lstset{emph={dim_id,lower_bound,upper_bound,var_1,var_2}, emphstyle=\itshape}
 \begin{lstlisting}
 !$claw define dimension dim_id(lower_bound:upper_bound) &
 [!$claw define dimension dim_id(lower_bound:upper_bound) &] ...
-!$claw parallelize [data(data(var_1[,var_2] ...)] [over (dim_id|:[,dim_id|:] ...)]
+!$claw parallelize [data(var_1[,var_2] ...)] [over (dim_id|:[,dim_id|:] ...)]
 \end{lstlisting}
 
 \textbf{Options and details}
@@ -23,28 +24,32 @@ \subsection{Column model abstraction}
 dimension can be either an integer constant or an integer variable. If a
 variable is given, it will be added in-order to the signature of the subroutine
 as an \lstinline!INTENT(IN)! parameter.
-\item \textit{data (optional)}: Define a list of variables to be promoted and 
+\item \textit{data (optional)}: Define a list of variables to be promoted and
 bypass the automatic promotion deduction.
-\item \textit{over (optional)}: Define the location of the new dimensions in promoted variables. The \lstinline!:! symbol reflects the position 
-of the current dimensions before the promotion.
+\item \textit{over (optional)}: Define the location of the new dimensions in
+promoted variables. The \lstinline!:! symbol reflects the position of the
+current dimensions before the promotion.
 \end{itemize}
 
-If the \lstinline!data! clause is omitted, the automatic promotion of variables 
+If the \lstinline!data! clause is omitted, the automatic promotion of variables
 is done as follows:
-Array variables declared with the \lstinline!INOUT! or \lstinline!OUT! intents
-are automatically promoted with the defined dimensions.
-In function of the target, intermediate scalar or array variables may also be 
+\begin{itemize}
+\item Array variables declared with the \lstinline!INOUT! or \lstinline!OUT!
+intents are automatically promoted with the defined dimensions.
+In function of the target, intermediate scalar or array variables may also be
 promoted.
-Scalar/array variables placed on the left hand-side of an assignment statement 
-will be promoted if the right hand-side references any variables already promoted.
-If the \lstinline!over! clause is omitted, the dimensions are
-added on the left-side following the the definition order if there is multiple new dimensions. The \lstinline!over! clause allows to change this behavior and to place 
-the new dimensions where needed.
-
-As the subroutine/function signature is updated by the \lstinline!parallelize! 
-directive with new dimensions, the call graph that leads to this 
-subroutine/function must be updated as well. For this purpose, the clause 
-\lstinline!forward! allows to replicated the changes along the call graph. 
+\item Scalar/array variables placed on the left hand-side of an assignment
+statement will be promoted if the right hand-side references any variables
+already promoted. If the \lstinline!over! clause is omitted, the dimensions are
+added on the left-side following the the definition order if there is multiple
+new dimensions. The \lstinline!over! clause allows to change this behavior and
+to place the new dimensions where needed.
+\end{itemize}
+
+As the subroutine/function signature is updated by the \lstinline!parallelize!
+directive with new dimensions, the call graph that leads to this
+subroutine/function must be updated as well. For this purpose, the clause
+\lstinline!forward! allows to replicated the changes along the call graph.
 Each subroutine/function along the call graph must be decorated with this
 directive.
 
@@ -59,15 +64,15 @@ \subsection{Column model abstraction}
 \end{lstlisting}
 
 The different variables declared in the current function/subroutine might be
-promoted if the call requires it. In this case, the array references in 
-the function/subroutine are updated accordingly. This can lead to extra 
+promoted if the call requires it. In this case, the array references in
+the function/subroutine are updated accordingly. This can lead to extra
 promotion of local scalar variables or arrays when needed.
 
-The first function call in the call graph might be an iteration over several
-column to reproduce the algorithm on the grid for testing purpose. If the 
-directive with the \lstinline!forward! clause is placed just before one or 
-several nested do statements with a function call, the corresponding do 
-statements will be removed and the function call updated accordingly. 
+The root function call in the call graph might be an iteration over several
+column to reproduce the algorithm on the grid for testing purpose. If the
+directive with the \lstinline!forward! clause is placed just before one or
+several nested do statements with a function call, the corresponding do
+statements will be removed and the function call updated accordingly.
 
 \begin{lstlisting}
 !$claw parallelize forward
@@ -79,7 +84,7 @@ \subsection{Column model abstraction}
 
 \textbf{Code example}\\
 \label{parallelize1}
-Simple example of a column model wrapped into a subroutine and parallelize with
+Simple example of a column model wrapped into a subroutine and parallelized with
 CLAW.
 
 Original code

documentation/claw_acc_transformation.tex

@@ -12,22 +12,25 @@ \subsubsection{Conditional primitive directives}
 !$claw omp target enter data
 \end{lstlisting}
 
-Primitive compiler directive like OpenACC or OpenMP can be enabled conditionally during the transformation. Examples on line 4 and 7 are conditional directives. They will be transformed into standard OpenACC respectively OpenMP directives only if the primitive directive language is specified for the transformation.
+Primitive compiler directive like OpenACC or OpenMP can be enabled conditionally
+during the transformation. Examples on line 4 and 7 are conditional directives.
+They will be transformed into standard OpenACC respectively OpenMP directives
+only if the primitive directive language is specified for the transformation.
 
 \subsubsection{Array notation to do statements}
 \lstset{emph={name,group_id,clause}, emphstyle=\itshape}
 \begin{lstlisting}
 !$claw array-transform [induction(name [[,] name]...)] [fusion [group(group_id)]] [parallel] [acc([clause [[,] clause]...])]
 
-  ! array notation assignment(s) 
-  
+  ! array notation assignment(s)
+
 [!$claw end array-transform]
 \end{lstlisting}
 
 Computations using the array notation are not suitable to be parallelized with
-language like OpenACC. The \textbf{array-transform} directive allows to transform those
-notation with the corresponding do statements which are more suitable for
-parallelization.
+language like OpenACC. The \textbf{array-transform} directive allows to
+transform those notation with the corresponding do statements which are more
+suitable for parallelization.
 
 The goal of this directive is to pass from an array notation assignment like
 this:
@@ -67,20 +70,23 @@ \subsubsection{Array notation to do statements}
 
 \textbf{Options and details}
 \begin{enumerate}
-\item \textit{induction}: Allow to name the induction variable created for the do statement.
-\item \textit{fusion}: Allow the extracted loop to be merged with other loops. Options 
+\item \textit{induction}: Allow to name the induction variable created for the
+do statement.
+\item \textit{fusion}: Allow the create do statement to be merged with other
+loops. Options
 are identical with the \textbf{loop-fusion} directive
 \item \textit{parallel}: Wrap the extracted loop in a parallel region.
-\item \textit{acc}: Define accelerator clauses that will be applied to the generated loops.
+\item \textit{acc}: Define accelerator clauses that will be applied to the
+generated loops.
 \end{enumerate}
 
 \textbf{Behavior with other directives}\\
-Directives declared before the \textbf{array-transform} directive will be kept in the
-generated code.
+Directives declared before the \textbf{array-transform} directive will be kept
+in the generated code.
 
 \textbf{Code example}\\
 \label{array-transform1}
-Example with array notation following the pragma statement. 
+Example with array notation following the pragma statement.
 
 Original code
 \begin{lstlisting}
@@ -107,4 +113,7 @@ \subsubsection{Array notation to do statements}
 END SUBROUTINE vector_add
 \end{lstlisting}
 
-More code examples in the appendix. Example with the induction and acc (see example \ref{array-transform2}). Example with fusion clause (see example \ref{array-transform3}). Example with 2-dimensional arrays (see example \ref{array-transform4}). 
+More code examples in the appendix. Example with the induction and acc clauses
+(see example \ref{array-transform2}). Example with fusion clause (see example
+\ref{array-transform3}). Example with 2-dimensional arrayx (see example
+\ref{array-transform4}).