Guide and Reference

Coding Your HPF Program

This section contains Parallel ESSL-specific application program coding requirements and considerations for HPF programs, as illustrated in the sample HPF programs in "Sample HPF Programs". For an example of the use of Parallel ESSL in a sample HPF application program solving a thermal diffusion problem, see Appendix B. "Sample Programs".

For further details on coding the CALL statement and other related aspects of HPF programs, see references [11], [17], [30], [31], [41], [44], and [45], as well as the following HPF manuals:

IBM XL High Performance Fortran for AIX User's Guide
IBM XL High Performance Fortran for AIX Language Reference

Coding the Calling Sequences

In HPF programs, the Parallel ESSL subroutines are invoked with the CALL statement, using the features of Fortran 90--generic interfaces, optional and keyword arguments, assumed-shape arrays, and modules. This section explains how these are used.

Using Extrinsic Procedures--The Parallel ESSL Subroutines

The Parallel ESSL subroutines are HPF_LOCAL extrinsic procedures, conforming to all restrictions imposed by HPF.

HPF requires that an explicit interface be provided for each extrinsic procedure entry in the scope where it is called, using an interface block. The interface blocks for the Parallel ESSL subroutines are provided for you in the module PESSL_HPF, so you do not have to code the interface blocks yourself. In the beginning of your HPF program, before any other specification statements, you must code the statement:

   use pessl_hpf

This gives the XL HPF compiler access to the interface blocks. It also enables the XL HPF compiler to detect, at compile time, certain errors in the calls to the Parallel ESSL subroutines. For examples of where to code this statement in your HPF program, see Figure 9 and Figure 10.

To understand the redistribution of data that occurs when using the Parallel ESSL HPF subroutines and the performance implications, see "Coding Tips for Optimizing Parallel Performance".

Generic Interfaces

The Parallel ESSL subroutines can be accessed through generic interfaces, where a single name covers one or more specific subroutines, whose arguments may differ in data type, precision, or rank (vector or matrix). The XL HPF compiler chooses the specific Parallel ESSL subroutine whose dummy arguments exactly match the characteristics of the actual arguments in the generic call statement. The use of generic interfaces for Parallel ESSL is dependent upon your coding the use statement described in "Using Extrinsic Procedures--The Parallel ESSL Subroutines".

The generic name used for each Parallel ESSL HPF subroutine is indicated in the "Syntax" section for each subroutine in Part 3 of this book.

For examples of how to specify a generic name in a Parallel ESSL call statement, see the sample programs in Figure 9 and Figure 10.

Optional and Keyword Arguments

As with standard Fortran 90, Parallel ESSL supports both optional and keyword arguments in its calling sequences.

Optional Arguments

Optional arguments do not have to be specified in the calling sequence when the Parallel ESSL subroutine is called. Optional arguments are indicated in the "Syntax" section for the subroutine in Part 3 of this book. Where optional arguments apply, the syntax shows two call statements in succession--the first lists only the required arguments, and the second lists both the required and optional arguments. For example, in the syntax for FFT, shown in FFT--Fourier Transforms in Two Dimensions, there are two call statements for case 1. The first call statement includes only the required argument x, and the second statement includes x, plus the optional arguments y, transpose, isign, and scale.

Keyword Arguments

Keywords are dummy argument names. You must not specify positional arguments after you specify the first keyword argument. Keyword arguments can be arranged in any order, following the positional arguments in the calling sequence. You may follow a (possibly empty) positional argument list by a keyword argument list. The dummy argument names are listed in the calling sequences in the "Syntax" section for each subroutine in Part 3 of this book. For example, in the syntax for case 1 in FFT, shown in FFT--Fourier Transforms in Two Dimensions, the dummy argument names are x, y, transpose, isign, scale.

Applying these rules, you could code any of the following call statements, and more, for the call statement shown in Figure 10.

Figure 8. Call Statements for FFT

   call fft(xc1, yc1, isign=isignc)
   call fft(xc1, y=yc1, isign=isignc)
   call fft(xc1, isign=isignc, y=yc1)
   call fft(x=xc1, y=yc1, isign=isignc)
   call fft(isign=isignc, y=yc1, x=xc1)
   call fft(scale=scalec, isign=isignc, y=yc1, x=xc1)
   call fft(xc1, yc1, transpose='T', isign=isignc)
   call fft(xc1, yc1, 'T', isign=isignc)
   call fft(xc1, yc1, 'T', isignc, scalec)
   call fft(xc1, yc1, 'T', isignc)
   call fft(xc1(1:n1,1:n2), yc1(1:n2,1:n1), isign=isignc)

Assumed-Shape Arrays and Problem Sizes

All array arguments in the Parallel ESSL HPF subroutines are assumed-shape arrays of one dimension (shape(:)), two dimensions (shape(:,:)), or three dimensions (shape(:,:,:)). Depending on the subroutine, you have several ways to specify, in the calling sequence, the vectors, matrices, and sequences that you want Parallel ESSL to use.

The assumed-shape arrays must have the exact shape required for the problem. For example, SYMM computes a matrix multiplication using three matrices A, B, and C. The required shape of these assumed-shape arrays depends on the value of the side argument. When side = 'L', Parallel ESSL computes C = alphaAB+betaC. For this case, the sizes of the assumed-shape arrays must satisfy the following:

size(a,1)=size(a,2)=size(b,1)=size(c,1)
size(b,2)=size(c,2)

These required sizes of the assumed-shape arrays are described in the "Notes" section for each subroutine in Part 3 of this book.

You have two ways to code the vectors, matrices, and sequences in the calling sequences:

If you want to solve a problem using the entire assumed-shape array, specify only the vector, matrix, or sequence argument in the calling sequence, such as shown here for a, b, and c:
```
   call symm(alpha, a, b, beta, c, uplo='U', side='L')
```
Most of the examples in Part 3 of this book use this technique--for example, see "Example 1".
If you want to solve a problem using a submatrix, specify the vector, matrix, or sequence in the calling sequence using Fortran 90 array sections--for example, A(IA:IA+M-1,JA:JA+N-1) or X(IX:IX+N-1), such as shown here for a, b, and c:
call symm(alpha, a(1:10,1:10), b(11:20,1:20), beta, c(1:10,1:20), uplo='U', side='L')
Some of the examples in Part 3 of this book use this technique--for example, see "Example 3" and "Example 4".

Coding the Directives for Distributing Your Data

Parallel ESSL supports the same data distribution techniques as HPF:

Block-cyclic--used for the PBLAS, Dense Linear Algebraic Equations, and Eigensystems Analysis subroutines. An example of coding the directives for block-cyclic distribution is shown in Figure 9.
Block--used for the Fourier Transforms, Banded Linear Algebraic Equations, and Random Number Generation subroutines. An example of coding the directives for block distribution is shown in Figure 10.

For a description of the various ways to code your directives for block-cyclic and block distribution, see "Distributing Data in an HPF Program".
Note: XL HPF only supports CYCLIC(n) distributions for n > 1 in HPF_LOCAL procedures, such as the Parallel ESSL HPF subroutines. The module PESSL_HPF contains the CYCLIC(n) data distribution directives corresponding to the block sizes listed in Table 30.

Sample HPF Programs

Following is a sample program calling a PBLAS subroutine, which uses block-cyclic distribution. It corresponds to "Example 1" for computing equation 2 (C <-- alphaBA+betaC) for SYMM on a 2 × 2 process grid. See the example for details about the input and output data for this sample program.

An example of the usage of a PBLAS subroutine is also shown in Appendix B. "Sample Programs". See "Program Main (HPF)".

Figure 9. PBLAS Sample Program Using Block-Cyclic Distribution

 program example_symm
      use pessl_hpf
      implicit none
      real(kind(1d0)), dimension(8,8)          :: a
      real(kind(1d0)), dimension(16,8)         :: b
      real(kind(1d0)), dimension(16,8)         :: c
      integer                                  :: i
      integer                                  :: j
! ...
! ... Initialize a and b with the data
! ... shown in Example 1 for SYMM
! ...(Steps not shown here)
! ...
! ... Block Cyclic Distribution on a 2d Process Grid
! ...
!hpf$ processors proc(2,2)
!hpf$ distribute(cyclic, cyclic) onto proc     :: a, b, c
! ...
! ... Call Parallel ESSL HPF Subroutine
! ...
      call symm(alpha=1.0d0, a=a, b=b, beta=0.0d0, c=c,            &
     &                 uplo='u', side='r')
 end program example_symm

Following is a sample program calling a Fourier transform subroutine, which uses block distribution. It corresponds to "Example 1" for the two-dimensional complex-to-complex Fourier transform computation for FFT.

An example of the usage of a Fourier transform subroutine is also shown in Appendix B. "Sample Programs". See "Module Fourier (HPF)".

Figure 10. Fourier Transform Sample Program Using Block Distribution

 program xpfft
      use pessl_hpf
      implicit none
      integer, parameter                       :: isignc = -1
      integer, parameter                       :: n1 = 8
      integer, parameter                       :: n2 = 6
      complex(kind(1d0)), dimension(n1,n2)     :: xc1
      complex(kind(1d0)), dimension(n2,n1)     :: yc1
      real(kind(1d0))                          :: scalec
      integer                                  :: i
      integer                                  :: j
!hpf$ processors p1(number_of_processors())
!hpf$ distribute (*, block) onto p1            :: xc1
!hpf$ distribute (*, block) onto p1            :: yc1
! ...
! ... Setup input
! ...
      xc1      = cmplx(0.0d0,0.0d0)
      xc1(1,1) = cmplx(float(n1*n2),0.0d0)
      scalec = 1.0d0/(float(n1*n2))
! ...
! ... Call Parallel ESSL HPF Subroutine
! ...
      call fft(xc1, yc1, isign=isignc, scale=scalec)
! ...
! ... Check the answers
! ...
      do j = 1, n1
       do i = 1, n2
       if (yc1(i,j) .ne. (1.0d0,0.0d0)) write(6,*) 'ERROR:', i, j, yc1(i,j)
       enddo
      endo
 end program xpfft

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]