User Manual for Parametric Fortran 1.0

							                    User Manual for Parametric Fortran 1.0
                                       Zhe Fu, Ben Pflaum

                                        September 3, 2004


1    Introduction
A Parametric Fortran program is a Fortran program in which parts, such as statements, expressions,
or subroutines, are parameterized by special variables. Every syntactic element of Fortran can be
parameterized. When the values of these parameters are given, a program generator can create a
Fortran program from the parameterized program, guided by these values.
    In this manual we first introduce the syntax of Parametric Fortran in Section 2. Then we
introduce how to install Parametric Fortran compiler. Finally we outline how to generate Fortran
programs from Parametric Fortran programs by two simple examples.


2    Syntax
The syntax of Parametric Fortran is a subset of Fortran with added constructs to allow for pa-
rameterization of Fortran syntactic objects. A syntactic object can be a subroutine, statement, a
sequence of statements, an expression, a variable, or a variable declaration. The current version of
Parametric Fortran compiler supports source files with one or more subroutines and declarations
of integer and real variables and arrays. The supported statements are currently limited to do
loops, if statements, and assignment statements. In addition, Parametric Fortran includes syntax
to parameterize a syntactic object, to parameterize only certain variables in a syntactic object, and
to stop the propagation of a parameter into a syntactic object or variable.
    A syntactic object can be parameterized using the parameterization construct, {p: f}, where
p is a parameter name and f is the syntactic object. This causes p to be propagated into every
syntactic object inside the brackets. For example in {p: a = b + c}, a, b, and c are parameterized
by p, as is the expression b + c and the assignment statement as a whole.
    To limit the parameterization to just a list of variables, you can use the form {p(a,b,...): f}
where (a,b,...) is the list of one or more variables that are to be parameterized by p. When
this construct is used only the variables in the list are parameterized and everything else is left
unparameterized.
    Parameterization of a syntactic object can be stopped with !. For a variable a, !a will prevent a
surrounding parameterization construct from parameterizing a. For larger syntactic objects !{...}
should be used. Using !{...} construct prevents the propagation of a parameter into the code
surrounded by the brackets. This can be used when a large part of code needs to be parameterized,
but contains a smaller part that should be left unaffected by the parameter.



                                                 1
3    Installation of Parametric Fortran Compiler
The distribution of Parametric Fortran 1.0 can be downloaded from
    http://web.engr.oregonstate.edu/~fuzh/PF/PF1.0.tar.gz.

After unzipping the file, the source code of the Parametric Fortran compiler is in the directory src.
The examples are in the directory examples.
    For compiling the source code of the Parametric Fortran compiler, you must have ghc 6.2 or
higher version on your computer. First, users need to set the value for the environment variable
PFHOME, which is the directory you unzip the Parametric Fortran distribution. For example, if you
use C Shell and the file PF1.0.tar.gz is unzipped in the directory /usr/local/PF1.0, you need
to put the following line in the file .cshrc.
    set PFHOME = /usr/local/PF1.0

For Windows 2000/XP users, the source code can be compiled by running
    pf.bat

in the directory src. For Unix users, the source code can be compiled by running
    pf

in the directory src. The binary file of the Parametric Fortran compiler will be in the directory
bin.
    We also provide binary file of the Parametric Fortran compiler for Windows 2000/XP users and
Sun-Solaris users. The binary file for Windows can be downloaded from
    http://web.engr.oregonstate.edu/~fuzh/PF/pfc.exe.

The binary file for Sun-Solaris can be downloaded from
    http://web.engr.oregonstate.edu/~fuzh/PF/pfc.


4    Selecting Parameter Types
The Parametric Fortran 1.0 provides 3 predefined parameter types, SimpleDim, Dim, and Slice.
Users can remove parameter types they do not need or add new parameter types provided by us in
the future distribution by modifying the file paramTypes in the directory config. For example, if
the following line is in the file paramTypes, all the 3 predefined parameter types will be selected.
    ["SimpleDim", "Dim", "Slice"]

If you want to remove the parameter type SimpleDim, you can put the following line into the file
instead.
    ["Dim", "Slice"]

Modifying the selection of parameter types needs to recompile the Parametric Fortran compiler. For
Windows 2000/XP users, after changing the file paramTypes, you can apply the change by running

                                                 2
    pf.bat
in the directory src. For Unix users, after changing the file paramTypes, you can apply the change
by running
    pf
in the directory src.


5     Examples
5.1      Array Addition for Arbitrary Dimensions
The following example shows how to write a Parametric Fortran subroutine to add two arrays of
arbitrary dimensions.1 Assume we have the following code in a file arrayAdd.pf, which is included
in the directory examples.

    { dim: subroutine arrayAdd(a, b, c)
        real :: a, b, c
        c = a + b
    end subroutine arrayAdd }

The program is parameterized by a parameter dim. The value of dim will guide the generation of
the Fortran subroutine. The brackets { and } delimit the scope of the dim parameter, that is, every
Fortran syntactic object in the scope is parameterized by dim.
    When the size of each dimension is the same, say, 100, we can use an integer to parameterize
the program. For example, if we want the generated Fortran subroutine to deal with 2-dimensional
arrays, we can put the following line into the file paramVals.
    [("dim", "SimpleDim 2")]
SimpleDim is a predefined constructor that converts an integer value to a parameter value. If we
then run the PF compiler
    pfc arrayAdd.pf arrayAdd.f
the Fortran source file arrayAdd.f will be generated in the current directory. The following is the
content of the generated file.
    subroutine arrayAdd(a, b, c)
        integer :: i1, i2
        real, dimension (1:100, 1:100) :: a, b, c
        do i1 = 1, 100
          do i2 = 1, 100
            c(i2, i1) = a(i2, i1) + b(i2, i1)
          end do
        end do
    end subroutine arrayAdd
   1
     This example is meant for illustration. Dimension-independent array addition is already supported in Fortran by
array syntax.

                                                         3
We can observe that in the generated program, a, b, and c are all 2-dimensional arrays. When a
variable declaration statement is parameterized by an integer dim, the variable will be declared as
a dim-dimensional array in the generated program. The assignment statement that assigns the sum
of a and b is wrapped by 2 loops over both dimensions, and index variables are added to each array
expression. The declarations for these index variables are also generated. This particular behavior
of the program generator is determined by the definition of the parameter type for dim.
    If the sizes of dimensions are different, for example, the first dimension is 1 to 100, and the
second dimension is 1 to 50, we can put the following line into the file paramVals.
   [("dim", "Dim [(1, 100), (1, 50)]")]

Dim is another constructor that converts a list of lower and upper boundaries to a parameter value.
If we then run the PF compiler again, the following Fortran code will be generated.
   subroutine arrayAdd(a, b, c)
       integer :: i1, i2
       real, dimension (1:100, 1:50) :: a, b, c
       do i1 = 1, 50
         do i2 = 1, 100
           c(i2, i1) = a(i2, i1) + b(i2, i1)
         end do
       end do
   end subroutine arrayAdd

5.2   Dimension-Independent Array Slicing
We can also define an array slicing subroutine, which slices an n-dimensional array on the dth
dimension. The following code is in the file slice.pf which is located in the directory examples.
   subroutine slice(a, k, b)
       {dim:   real :: a}
       {slice: real :: b}
       integer :: k
       {slice: b = a(!k)}
   end subroutine slice

In the subroutine slice, a is the input n-dimensional array, b is the result (n − 1)-dimensional
array, and k is the index on the dth dimension of the input array. This program is parameterized
by two parameters. The parameter dim is an integer representing the number of dimensions of a.
It only parameterizes the declaration of a. The parameter slice is a pair of integers of the form
(n,d), representing that the generated code slices the dth dimension of an n-dimensional array.
The parameter slice is not a Fortran variable, but a variable of Parametric Fortran. Therefore, it
causes no conflict with the name of the subroutine.
    For example, if we want the generated Fortran subroutine to slice a 3-dimensional array on the
second dimension, we can put the following line into the file paramVals.
   [("dim", "SimpleDim 2"), ("slice", "Slice 3 2")]

If we then run the PF compiler

                                                4
   pfc slice.pf slice.f

the Fortran source file slice.f will be generated in the current directory. The following is the
content of the generated file.

   subroutine slice(a, k, b)
       integer :: i2, i3
       real, dimension (1:100, 1:100, 1:100) :: a
       real, dimension (1:100, 1:100) :: b
       integer :: k
       do i2 = 1, 100
         do i3 = 1, 100
           b(i3, i2) = a(i3, k, i2)
         end do
       end do
   end subroutine slice

The declaration of a is parameterized by an integer, which has the same meaning as in the first
example. The declaration of b is parameterized by the parameter slice, which is a pair of integers
(n,d). This parameterization means that in the generated program b has (n-1) dimensions and
that array indices are added such that the already existing index expression (in the example: k)
will appear at the dth dimension.




                                                5