Compaq KAP Fortran/OpenMP
for Tru64 UNIX

Order Number: AA--QMB5G--TE

This document provides information about how to run and use Compaq KAP Fortran/OpenMP on Compaq Tru64 UNIX systems.

Revision/Update Information: This is a revised document.

Operating System and Version: Compaq Tru64 UNIX Versions 4.0F, 5.0, and 5.0A

Software Version: Version 4.3
Compaq Fortran Version 5.3

Compaq Computer Corporation
Houston, Texas

© 1995 Compaq Computer Corporation

© 1995 Kuck & Associates, Inc.

Compaq, the Compaq logo, Compaq C, and Compaq Fortran, Registered in U.S. Patent and Trademark Office.

KAP is a trademark of Kuck & Associates, Inc.

UNIX is a registered trademark of The Open Group.

All other product names mentioned herein may be trademarks or registered trademarks of their respective companies.

Compaq shall not be liable for technical or editorial errors or omissions contained herein. The information in this document is subject to change without notice.

Contents

Index

This document provides information about how to use Compaq KAP Fortran/OpenMP software on Compaq Tru64 UNIX systems.

Intended Audience

This document is a guide for Compaq KAP users working with Fortran 90 on Compaq Tru64 UNIX systems.

Structure of This Document

This document is organized into the following chapters and appendixes:

• Chapter 1 provides an introduction to Compaq KAP Fortran/OpenMP for Compaq Tru64 UNIX.
• Chapter 2 presents information on how to run Compaq KAP.
• Chapter 3 presents information on how to compile and run programs with KAP on symmetric multiprocessor systems.
• Chapter 4 describes how Compaq KAP treats Fortran 90 constructs.
• Chapter 5 describes the command switches used to alter KAP defaults, such as setting Compaq KAP optimization levels and enabling or disabling classes of transformations.
• Chapter 6 presents directives to alter Compaq KAP defaults. Directives are like command switches, except they appear within a program and may be changed on a loop-by-loop basis.
• Chapter 7 specifies KAP assertions that can provide KAP with additional information about the input program that would normally be unknown at compile time.
• Chapter 8 provides additional information on subprogram inlining, Interprocedural Analysis (IPA), and the KAP command switches and directives that control them.
• Chapter 9 shows examples of the transformations that KAP performs to enhance the code.
• Chapter 10 describes the information available in the optional KAP listing and the messages that KAP produces.
• Appendix A lists the Compaq extensions to Fortran 90.
• Appendix B describes data dependence analysis and explains how KAP uses this information to determine if a given loop can be optimized.
• Appendix C presents a variety of OpenMP examples.
• Appendix D describes the use of Parallel Computing Forum directives.
• Appendix E contains a warning about processing programs that violate the rules of Fortran 90.
• Appendix F lists the diagnostic messages that can appear in the optional annotated program listing.

Associated Documents

This document is part of the Compaq KAP documentation set that also includes:

• Compaq KAP Fortran/OpenMP for Tru64 UNIX Installation Guide
• Compaq KAP Fortran/OpenMP for Tru64 UNIX Cover Letter
• Compaq KAP Fortran/OpenMP for Tru64 UNIX Quick Reference

Conventions

The following are equivalent terms in this document: Compaq KAP, KAP, and Compaq KAP Fortran/OpenMP.

The following terms are used interchangeably in this document: Compaq Fortran and Fortran 90.

The Fortran 90 icon indicates that the section of information immediately following is unique to Fortran 90 (does not apply to Fortran 77).

Other conventions used in this guide are as follows:

Convention	Description
italic type	Italic type indicates complete titles of manuals and keywords, as well as product names.
lowercase	Commands are usually presented in lowercase. The KAP command line, however, is not case sensitive.
< >	Angle brackets denote command input you replace with the appropriate value.
( )	Parentheses containing a single command value denote the default value. For example, (-optimize=5) denotes 5 is the default value. Parentheses containing hyphenated value ranges denote that you choose a value from the range.
[ ]	Square brackets denote optional items.
Defaults	Unless specified otherwise, the code examples in this manual were run with the switches -optimize=5, -roundoff=3, -scalaropt=3, and -unroll=1.

Compaq KAP Fortran/OpenMP is a Fortran source-to-source preprocessor that restructures Fortran 90 code for improved performance and better utilization of the memory hierarchy of Tru64 UNIX systems. Additionally, KAP performs parallel decomposition to take advantage of shared memory and symmetric multiprocessors. By eliminating inefficiencies and bottlenecks, KAP enables Tru64 UNIX users to get their answers faster, without time-consuming hand-recoding of their applications programs.

The KAP conversion process is designed to operate effectively without user intervention. KAP provides a large set of command-line switches, directives, and assertions that the advanced user can use for even better results. The KAP generated listing includes messages and questions that point out parts of the program that might be further improved.

KAP optimizations include:

• Memory Management for Data Locality
• Subprogram Inlining
• Loop Reordering
• Induction Variable Recognition
• Global Forward Substitution
• Variable Lifetime Analysis
• Invariant IF Restructuring
• Loop Peeling
• Scalar Optimizations

KAP is especially useful for programs characterized by:

• Intensive CPU usage
• Large number of loops and/or loops having large loop bounds
• Action on large data sets
• Significant reuse of data
• Large number of procedure calls
• Large number of floating-point operations

This chapter describes the commands necessary to execute KAP on Tru64 UNIX systems.

Compaq KAP Fortran/OpenMP can be run in either of two modes:

• The recommended mode is to invoke KAP with the kf90 command. The kf90 command accepts Fortran 90 or Fortran 77 source as input, calls KAP to preprocess and optimize that input, calls the Compaq Fortran compiler and the linker, and passes all of the compiler switches to the Compaq Fortran compiler and all of the linker switches to the linker.
• KAP can also act as a standalone preprocessor with the kapf90 command that does not call the compiler or the linker.

The following provides information and restrictions:

• The following command switches provide maximum general optimization: -optimize=5, -roundoff=3, -scalaropt=3. These are the default settings for these switches.
  See Section 2.3 about KAP execution using the kf90 driver for an explanation of how to pass command switches to KAP and Chapter 5 for details about what is controlled by each switch's levels.
• KAP treats the source file format as either free or fixed depending on the source file extension and the format-related switches used to compile the file. For a complete explanation, see Table 2-1.
• The default input line length for Compaq KAP Fortran/OpenMP fixed-form files is 72 columns. You can specify longer lines with the -scan command switch.
• If a FORMAT statement for a Hollerith constant is continued on a second line and the first line has trailing blanks, KAP removes the trailing blanks, causing an error message from the Compaq Fortran compiler. This is also true for quoted strings that are continued over more than one line.
  To avoid this problem, put the entire string on one line, or terminate the first line of the Hollerith constant with something other than a blank.
• KAP is not case sensitive by default.
• KAP does not optimize loop nests with noninteger indices, such as:

  DO 100 x=0.0, 10.0, 0.2

• KAP does not support Fortran EXTERNAL * <name>.

KAP is installed on the Tru64 UNIX system with the system command setld. See the Compaq KAP Fortran/OpenMP for Tru64 UNIX Installation Guide for details.

2.3 Compiling a Program Using the kf90 Driver

The kf90 command invokes a driver program that automatically calls KAP, the Compaq Fortran compiler, and the linker.

• Passing default KAP switch settings to kf90
  Because kf90 calls KAP and the Compaq Fortran compiler, you can substitute the kf90 command for the Fortran 90 command. For example, to use kf90 to compile myprog.f90 with the default KAP switch settings, use the command:

  kf90 myprog.f90

  
  The kf90 command uses the KAP preprocessor on myprog.f90, compiles the result with the Compaq Fortran compiler, links the object code into an executable image, and produces the following files:

  • myprog.cmp.f90 --- the optimized source file
  • myprog.out --- the annotated source file showing default KAP switch settings
  • a.out --- the executable file
  
  To see a list of the KAP switches and Compaq Fortran compiler switches passed by kf90, use the -v switch as follows:

  kf90 myprog.f90 -v

  
  An example of the output is as follows:

  oursmp> kf90 -v matmul.f timing_fortran.o /usr/bin/kapf90 -cmp=./matmul.cmp.f matmul.f -tune=EV4 -nofree KAP/Tru64_U_F90 4.3 k3105167 000519 30-May-2000 09:27:21 KAP/Tru64_U_F90 4.3 k3105167 000519 : 0 errors in file matmul.f /usr/bin/f90 -fast -v ./matmul.cmp.f timing_fortran.o -tune host -non_shared /usr/lib/cmplrs/fort90/decfort90 -platinum -fast -tune host -non_shared -I/usr/lib/cmplrs/hpfrtl -o /tmp/forAAAaaupma.o ./matmul.cmp.f /usr/bin/cc -fast -v -tune host -non_shared /usr/lib/cmplrs/fort90/for_main.o /tmp/forAAAaaupma.o -O4 timing_fortran.o -qlshpf -lUfor -lfor -lFutil -lm -lots -qlc_r /usr/lib/cmplrs/cc/ld -g0 -O4 -non_shared /usr/lib/cmplrs/cc/crt0.o /usr/lib/cmplrs/fort90/for_main.o /tmp/forAAAaaupma.o timing_fortran.o -qlshpf -qlc_r -lUfor -lfor -lFutil -lm -lots -lc /usr/lib/cmplrs/cc/ld: 0.45u 0.39s 0:06 13% 0+28k 305+173io 14pf+0w 28stk+4752mem

  
  The final resource usage appears in C-shell format at the end.

• Passing KAP switches to kf90
  The -fkapargs switch specifies one or more KAP command switches to the preprocessor. For example, to use kf90 to optimize and compile the file myprog.f90 using KAP switches for general optimization, use the command:

  kf90 -fkapargs='-optimize=5 -roundoff=3 -scalaropt=3 -list=myprog_annotated.lis' \ myprog.f90

  
  The following files result:

  • myprog.cmp.f90 --- the optimized source file
  • myprog_annotated.lis --- the annotated source file renamed -list switch
  • a.out --- the executable file
  
  For descriptions of all KAP command switches, see Chapter 5.
• Passing Compaq Fortran compiler switches to kf90
  Any command-line switch that is valid for the Compaq Fortran compiler or the linker is valid for the kf90 command. You can specify compiler switches and KAP switches on the same line. For example, to optimize and compile the file myprog.f90 using KAP switches for general optimization and to specify the name of the executable file with the Compaq Fortran compiler switch, -o, use the following command:

  kf90 -fkapargs='-optimize=5 -roundoff=3 -scalaropt=3' -o=myprog.exe myprog.f90

  
  The following files result:

  • myprog.cmp.f90 --- the optimized source file
  • myprog.out --- the annotated source file
  • myprog.exe --- the executable file renamed with the -o switch
  
  The kf90 command specifies the Compaq Fortran compiler switches -notransform_loops, -lpthread, and -fast, by default. To override any of the individual compiler switches encompassed by -fast, specify them on the kf90 command line. For example, the following command sets the compiler switch -math_library accurate and overrides the default -math_library noaccurate set by -fast:

  kf90 -math_library accurate myprog.f90

  
  For information about the -fast compiler switch, see your Fortran user manual.

The kf90 command sets the compiler switch -tune host by default. The -tune host switch causes the compiler to optimize to the host architecture. For example, if you want to optimize for the ev5 architecture but are compiling on an ev4 system, you should override the default setting of the -tune switch, as follows:

kf90 -tune ev5 myprog.f90

The kf90 command specifies the linker switches -lpthread and -non_shared by default. The -non_shared switch causes the image to be linked with archive libraries instead of with shared libraries. To override the -non_shared default, specify -call_shared on the command line, for example:

kf90 -call_shared myprog.f90

The kf90 driver accepts either Fortran 90 or Fortran 77 source input. The exception is that the Compaq Fortran compiler rejects comment lines beginning with C as syntax errors. Like the f90 command, the kf90 command assumes by default that source files with an extension of .f90 are free format, and source files with an extension of .f, .for, or .FOR are fixed format. You can override these defaults by using a format-related switch with either the KAP preprocessor or with the Compaq Fortran compiler. The format-related compiler switches are -free and -fixed. The corresponding KAP preprocessor switches are -freeformat and -nofreeformat. Table 2-1 lists combinations of switches and file extensions and the resulting assumption KAP makes about the format of the source file.

Table 2-1 kf90 Assumed Source Format Based on Switch Settings and File Extensions

Switches		Source File Extension
KAP	F90	.f90	.f, .for, .FOR
default	default	free	fixed
-freeformat	default	free	free
-nofreeformat	default	fixed	fixed
default	-free	free	free
default	-fixed	fixed	fixed
-freeformat	-fixed	KAP issues error message
-nofreeformat	-free	KAP issues error message

For more information about the -[no]freeformat switch, see Section 5.4.7. For more information about the -free and -fixed switches, see your Fortran user guide.

2.4 Compiling a Program Containing C Preprocessor Directives Using kf90

If your Fortran program contains C preprocessor directives and you do not want to use any additional C preprocessor directives in the kf90 command line, use the Compaq Fortran compiler switch -cpp, as follows:

kf90 -cpp myprog.f90

The -cpp switch causes the C preprocessor to run on your Fortran program before compilation.

In the event you want to use C preprocessor directives in the kf90 command line, you must also include the C preprocessor switch -C to avoid errors resulting from C comment lines. For example, in the following kf90 command line where -Dfoo is a C preprocessor switch, you must include -C, as follows:

kf90 -cpp -C -Dfoo myprog.f90

The kf90 driver does not set the -C switch when you use C preprocessor directives in the command line. Without the -C switch, an error message results from the following program lines:

PRINT 5 5 FORMAT(//,'above are 2 blank lines') end

2.5 Optimized Programs

The kf90 command saves the optimized version of your source program in the current directory for use in debugging and profiling. The default file extension of the optimized source depends on the input file extension, as follows:

File Extension of Input	File Extension of Transformed Source
.f90	.cmp.f90
.f, .for, .FOR	.cmp.f

The Compaq Fortran compiler uses the file extension of the optimized source file to determine the source format. Compaq Fortran assumes sources with a file extension of .f90 are free format and sources with a file extension of .f, .for, or .FOR are fixed format. You can override the defaults by using the Compaq Fortran compiler switches -free and -fixed. You can override the naming of the optimized program by using the -cmp switch. See the -cmp description in Section 5.8.1.

2.6 KAP Command Switches Determined by Compiler Switches

Some Compaq Fortran compiler switches automatically set KAP command switches or alter the default KAP switch settings.

Explicitly calling the compiler switch -assume=accuracy causes KAP to be called with -roundoff=0. Otherwise, the KAP command switch -roundoff defaults to -roundoff=3.

Explicitly calling the compiler switch -nof77 causes KAP to be called with the -onetrip command switch.

Explicitly calling the compiler switch -noi4 causes KAP to be called with the command switches -integer=2 and -logical=2; otherwise, the defaults are -integer=4 and -logical=4.