NAG Fortran SMP Library, Release 1.1 FSNTI11DD Windows NT Digital Visual Fortran 90, Double Precision Users' Note Contents 1. Introduction 2. General Information 2.1. Accessing the Library 2.2. Interpretation of Bold Italicised Terms 2.3. Example Programs 2.4. Explicit Output from NAG Routines 2.5. User Documentation 2.6. Double Precision Complex 2.7. Interface Blocks 3. Routine-specific Information 4. Additional Services from NAG 5. Support from NAG 6. NAG Users Association 1. Introduction This document is essential reading for every user of the NAG Fortran SMP Library Implementation specified in the title. It provides implementation-specific detail that augments the information provided in the NAG Fortran SMP Library on-line documentation (TextWare) and in the NAG Fortran SMP Library Manual. Wherever these refer to the "Users' Note for your implementation", the user should consult this note. NAG recommends that users read the following minimum reference material before calling any library routine: (a) Introduction to the NAG Fortran SMP Library (b) Essential Introduction to the NAG Fortran Library (c) Chapter Introduction (d) Routine Document (e) Implementation-specific Users' Note Items (a), (b), (c) and (d) are included in the on-line documentation or in the NAG Fortran SMP Library Manual; item (e) is this document which is provided in plain text form. Items (a), (b) and (e) are also supplied on the distribution medium, item (a) in HTML form. 2. General Information 2.1. Accessing the Library The NAG Fortran SMP Library may be linked directly with a user program source.for, say, in the following manner: DF /threads source.for naglibsmp.lib assuming that the directory containing the library naglibsmp.lib is included in the LIB environment variable. This will produce the executable file source.exe. Before executing the program, the environment variable OMP_NUM_THREADS should be set to the number of processors on the system. The environment variable MKL_NPROCS (used to implement parallelism within routines contained in the Intel MKL Library) should be set to 1 when OMP_NUM_THREADS is set to a number greater than 1, as the two forms of parallelism are currently not compatible, e.g. set OMP_NUM_THREADS=4 set MKL_NPROCS=1 2.2. Interpretation of Bold Italicised Terms For this double precision implementation, the bold italicised terms used in the on-line documentation and in the NAG Fortran SMP Library Manual (and shown here as //.....// ) should be interpreted as: //real// - DOUBLE PRECISION //basic precision// - double precision //complex// - COMPLEX (KIND=KIND(1.0D0)) //additional precision// - quadruple precision //machine precision// - the machine precision, see the value returned by X02AJF in Section 4 below Thus a parameter described as //real// should be declared as DOUBLE PRECISION in the user's program. If a routine accumulates an inner product in //additional precision//, it is using software to simulate quadruple precision. Additional bold italicised terms are used in the example programs in the on-line documentation and in the NAG Fortran SMP Library Manual and they must be interpreted as follows: //real// as an intrinsic function name - DBLE //imag// - AIMAG //cmplx// - CMPLX with the addition of a final parameter KIND=KIND(1.0D0) //conjg// - CONJG //e// in constants, e.g. 1.0//e//-4 - D, e.g. 1.0D-4 //e// in formats, e.g. //e//12.4 - D, e.g. D12.4 All references to routines in Chapter F07 - Linear Equations (LAPACK) and Chapter F08 - Least-squares and Eigenvalue Problems (LAPACK) use the LAPACK name, not the NAG F07/F08 name. The LAPACK name is precision dependent, and hence the name appears in a bold italicised typeface. The examples in the on-line documentation use the single precision form of the LAPACK name. To convert this name to its double precision form, change the first character either from S to D or C to Z as appropriate. For example: //sgetrf// refers to the LAPACK routine name - DGETRF //cpotrs// - ZPOTRS 2.3. Example Programs In the on-line documentation and in the NAG Fortran SMP Library Manual, routine documents present the example programs in a generalised form, using bold italicised terms as described in Section 2.2 above. The example programs supplied to a site in machine-readable form have been modified as necessary so that they are suitable for immediate execution. The example programs are most easily accessed by using the batch file nagex.bat, which will provide you with a copy of an example program (and its data, if any), compile the program and link it with the library. Finally, the executable program will be run. The example program concerned is specified by the argument to nagex.bat. For example, create the directory c:\test, make c:\test the current directory, copy the file nagex.bat to it and then give the command: nagex c06eaf This will copy the example program and its data into the directory c:\test and process them to produce the example program results in the file c06eafe.res. 2.4. Explicit Output from NAG Routines Certain routines produce explicit error messages and advisory messages via output units which either have default values or can be reset by using X04AAF for error messages and X04ABF for advisory messages. (The default values are given in Section 4 below). The maximum record lengths of error messages and advisory messages (including carriage control characters) are 80 characters, except where otherwise specified. 2.5. User Documentation The following machine-readable information files are provided by NAG on the library distribution medium. Please consult your local advisory service or NAG Site Contact for further details: un.txt - Users' Note (this document) essint - the Essential Introduction to the NAG Fortran Library summary - a brief summary of the routines calls - a list of routines called directly or indirectly by each routine in the library, and by each example program called - for each routine in the library (including auxiliaries), a list of routines and example programs which call it directly or indirectly SMP.html - HTML page describing the NAG Fortran SMP Library See Section 4 below for additional documentation available from NAG. 2.6. Double Precision Complex The double precision complex data type is not standard in Fortran 77, but many compilers (including Digital Visual Fortran 90) support it. Fortran 90 has standardised this data type, and all Fortran 77 COMPLEX*16 (or DOUBLE COMPLEX) declarations may be replaced by Fortran 90 syntax. For the Digital Visual Fortran 90 compiler the declaration for a variable Z becomes COMPLEX (KIND=2) Z or the more portable alternative (because KIND numbers are not standardised) COMPLEX (KIND=KIND(1.0D0)) Z If you have many such declarations it may be more convenient to define a constant with the KIND number INTEGER, PARAMETER :: DP = KIND(1.0D0) COMPLEX (KIND=DP) Z 2.7. Interface Blocks The NAG Fortran SMP Library Interface Blocks define the type and arguments of each user callable NAG Fortran SMP Library routine. These are not essential to calling the NAG Fortran SMP Library from Fortran 90 programs. Their purpose is to allow the Fortran 90 compiler to check that NAG Fortran SMP Library routines are called correctly. The interface blocks enable the compiler to check that: (a) Subroutines are called as such (b) Functions are declared with the right type (c) The correct number of arguments are passed (d) All arguments match in type and structure These interface blocks have been generated automatically by analysing the source code for the NAG Fortran SMP Library. As a consequence, and because these files have been thoroughly tested, they are more reliable than writing your own declarations. The NAG Fortran SMP Library Interface Block files are organised by Library chapter. The module names are: nag_f77_a_chapter nag_f77_c_chapter nag_f77_d_chapter nag_f77_e_chapter nag_f77_f_chapter nag_f77_g_chapter nag_f77_h_chapter nag_f77_m_chapter nag_f77_p_chapter nag_f77_s_chapter nag_f77_x_chapter These are supplied in pre-compiled form (.mod files). If, for example, nag_f77_s_chapter is required, it must be copied to the current directory. In order to make use of these modules from existing Fortran 77 code the following changes need to be made: (a) Add a USE statement for each of the module files for the chapters of the NAG Fortran SMP Library that your program calls directly. Often only one USE statement will be required. (b) Delete all EXTERNAL statements for NAG Fortran SMP Library routines. These are now declared in the module(s). (c) Delete the type declarations for any NAG Fortran SMP Library functions. These are now declared in the module(s). These changes are illustrated by showing the conversion of the Fortran 77 version of the example program for NAG Fortran SMP Library routine S18DEF. Please note that this is not exactly the same as the example program that is distributed with this implementation. Each change is surrounded by comments boxed with asterisks. The previous Fortran 77 statement is shown commented out followed, where appropriate, with the new Fortran 90 line. * S18DEF Example Program Text * Mark 14 Revised. NAG Copyright 1989. ******************************************************************* * Add USE statement for relevant chapters * USE nag_f77_s_chapter * * ******************************************************************* * .. Parameters .. INTEGER NIN, NOUT PARAMETER (NIN=5,NOUT=6) INTEGER N PARAMETER (N=2) * .. Local Scalars .. ******************************************************************* * * * COMPLEX*16 may be changed to COMPLEX(KIND=...). * C COMPLEX*16 Z * * COMPLEX(KIND=KIND(1.0D0)) Z * * ******************************************************************* DOUBLE PRECISION FNU INTEGER IFAIL, NZ CHARACTER*1 SCALE * .. Local Arrays .. ******************************************************************* * COMPLEX*16 may be changed to COMPLEX(KIND=...). * C COMPLEX*16 CY(N) COMPLEX(KIND=KIND(1.0D0)) CY(N) * * ******************************************************************* * .. External Subroutines .. ******************************************************************* * EXTERNAL declarations need to be removed (and type declarations * * for functions). * C EXTERNAL S18DEF * * ******************************************************************* * .. Executable Statements .. WRITE (NOUT,*) 'S18DEF Example Program Results' * Skip heading in data file READ (NIN,*) WRITE (NOUT,*) WRITE (NOUT,99999) 'Calling with N =', N WRITE (NOUT,*) WRITE (NOUT,*) +' FNU Z SCALE CY(1) CY(2) + NZ IFAIL' WRITE (NOUT,*) 20 READ (NIN,*,END=40) FNU, Z, SCALE IFAIL = 0 * CALL S18DEF(FNU,Z,N,SCALE,CY,NZ,IFAIL) * WRITE (NOUT,99998) FNU, Z, SCALE, CY(1), CY(2), NZ, IFAIL GO TO 20 40 STOP * 99999 FORMAT (1X,A,I2) 99998 FORMAT (1X,F7.4,' (',F7.3,',',F7.3,') ',A, + 2(' (',F7.3,',',F7.3,')'),I4,I4) END 3. Routine-specific Information Any further information which applies to one or more routines in this implementation is listed below, chapter by chapter. (a) C06 The following C06 chapter routines have implementation-specific workspace requirements: C06FFF C06FJF C06PAF C06PCF C06PFF C06PJF C06PKF C06PPF C06PRF C06PUF C06PXF C06RAF C06RBF C06RCF C06RDF The actual length of work array used by a routine during a specific CALL is returned in WORK(1). Routine Workspace Array Dimension ------- ------------------------- C06FFF LWORK = 2*N + 2*MAX{ND(i)} N = ND(1)*ND(2)*...*ND(NDIM) C06FJF LWORK = 2*N + 2*ND(L) N = ND(1)*ND(2)*...*ND(NDIM) C06PAF LWORK = N C06PCF LWORK = 2*N C06PFF The number of true dimensions, NDIMT, is defined here as the number of elements of the array ND(1:NDIM) whose value is greater than 1. If ND(L) = 1 then LWORK = 1 Else If ND(i) = 1 for all i < L (L is the first true dimension) then LWORK = N + ND(L) Else If ND(i) = 1 for all i > L (L is the last true dimension) then LWORK = N + ND(L) Else (L is an intermediate dimension) LWORK = ND(1)*ND(2)*...*ND(L) + ND(L) Note: N + ND(L) is always big enough. C06PJF The number of true dimensions, NDIMT, is defined here as the number of elements of the array ND(1:NDIM) whose value is greater than 1. If NDIMT = 1 then see C06PCF Else If NDIMT = 2 then see C06PUF Else If NDIMT = 3 then see C06PXF Else (NDIMT > 3, apply C06PFF for each dimension) LWORK = N + max{ND(i), i = 1,..,NDIM} C06PKF LWORK = 2*N C06PPF LWORK = M*N + 2*N C06PRF LWORK = M*N + N C06PUF If N = 1 (1D length M) then LWORK = 2*M Else If M = 1 (1D length N) then LWORK = 2*N Else (genuine 2D problem) LWORK = M*N + M + N C06PXF If N1 = 1 or N2 = 1 or N3 = 1 (Not 3D) then see C06PUF (e.g. N1 = 1 : N2 -> M, N3 -> N) Else (genuine 3D problem) LWORK = N1*N2*N3 + N1 + N2 + N3 C06RAF LWORK = M*N + 2*N C06RBF LWORK = M*N + 2*N C06RCF LWORK = M*N + 2*N C06RDF LWORK = M*N + 2 (b) D03 The example programs for D03RAF and D03RBF take much longer to run than other examples. (c) F06, F07 and F08 In this implementation all calls to the Basic Linear Algebra Subprograms (BLAS) are implemented by calls to the Intel MKL Library. (d) G02 The value of ACC, the machine-dependent constant mentioned in several documents in the chapter, is 1.0D-13. (e) P01 On hard failure, P01ABF writes the error message to the error message unit specified by X04AAF and then stops. (f) S07 - S21 The constants referred to in the on-line documentation have the following values in this implementation: S07AAF F(1) = 1.0D+13 F(2) = 1.0D-14 S10AAF E(1) = 185.0 S10ABF E(1) = 708.0 S10ACF E(1) = 708.0 S13AAF x(hi) = 708.3 S13ACF x(hi) = 1.0D+16 S13ADF x(hi) = 1.0D+17 S14AAF IFAIL = 1 if X > 170.0 IFAIL = 2 if X < -170.0 IFAIL = 3 if abs(X) < 2.23D-308 S14ABF IFAIL = 2 if X > 2.55D+305 S15ADF x(hi) = 26.6 x(low) = -6.25 S15AEF x(hi) = 6.25 S17ACF IFAIL = 1 if X > 1.0D+16 S17ADF IFAIL = 1 if X > 1.0D+16 IFAIL = 3 if 0.0 < X <= 2.23D-308 S17AEF IFAIL = 1 if abs(X) > 1.0D+16 S17AFF IFAIL = 1 if abs(X) > 1.0D+16 S17AGF IFAIL = 1 if X > 103.8 IFAIL = 2 if X < -5.6D+10 S17AHF IFAIL = 1 if X > 104.1 IFAIL = 2 if X < -5.6D+10 S17AJF IFAIL = 1 if X > 104.1 IFAIL = 2 if X < -1.8D+9 S17AKF IFAIL = 1 if X > 104.1 IFAIL = 2 if X < -1.8D+9 S17DCF IFAIL = 2 if abs (Z) < 3.93D-305 IFAIL = 4 if abs (Z) or FNU+N-1 > 3.27D+4 IFAIL = 5 if abs (Z) or FNU+N-1 > 1.07D+9 S17DEF IFAIL = 2 if imag (Z) > 700.0 IFAIL = 3 if abs (Z) or FNU+N-1 > 3.27D+4 IFAIL = 4 if abs (Z) or FNU+N-1 > 1.07D+9 S17DGF IFAIL = 3 if abs (Z) > 1.02D+3 IFAIL = 4 if abs (Z) > 1.04D+6 S17DHF IFAIL = 3 if abs (Z) > 1.02D+3 IFAIL = 4 if abs (Z) > 1.04D+6 S17DLF IFAIL = 2 if abs (Z) < 3.93D-305 IFAIL = 4 if abs (Z) or FNU+N-1 > 3.27D+4 IFAIL = 5 if abs (Z) or FNU+N-1 > 1.07D+9 S18ADF IFAIL = 2 if 0.0 < X <= 2.23D-308 S18AEF IFAIL = 1 if abs(X) > 711.6 S18AFF IFAIL = 1 if abs(X) > 711.6 S18CDF IFAIL = 2 if 0.0 < X <= 2.23D-308 S18DCF IFAIL = 2 if abs (Z) < 3.93D-305 IFAIL = 4 if abs (Z) or FNU+N-1 > 3.27D+4 IFAIL = 5 if abs (Z) or FNU+N-1 > 1.07D+9 S18DEF IFAIL = 2 if real (Z) > 700.0 IFAIL = 3 if abs (Z) or FNU+N-1 > 3.27D+4 IFAIL = 4 if abs (Z) or FNU+N-1 > 1.07D+9 S19AAF IFAIL = 1 if abs(x) >= 49.50 S19ABF IFAIL = 1 if abs(x) >= 49.50 S19ACF IFAIL = 1 if X > 997.26 S19ADF IFAIL = 1 if X > 997.26 S21BCF IFAIL = 3 if an argument < 1.579D-205 IFAIL = 4 if an argument >= 3.774D+202 S21BDF IFAIL = 3 if an argument < 2.820D-103 IFAIL = 4 if an argument >= 1.404D+102 (g) X01 The values of the mathematical constants are: X01AAF (PI) = 3.1415926535897932 X01ABF (GAMMA) = 0.5772156649015329 (h) X02 The values of the machine constants are: The basic parameters of the model X02BHF = 2 X02BJF = 53 X02BKF = -1021 X02BLF = 1024 X02DJF = .TRUE. Derived parameters of floating-point arithmetic X02AJF = Z'3CA0000000000001' ( 1.11022302462516D-16 ) X02AKF = Z'0010000000000000' ( 2.22507385850721D-308 ) X02ALF = Z'7FEFFFFFFFFFFFFF' ( 1.79769313486231D+308 ) X02AMF = Z'0010000000000000' ( 2.22507385850721D-308 ) X02ANF = Z'0010000000000000' ( 2.22507385850721D-308 ) Parameters of other aspects of the computing environment X02AHF = Z'43F0000000000000' ( 1.84467440737095D+19 ) X02BBF = 2147483647 X02BEF = 15 X02DAF = .FALSE. (i) X04 The default output units for error and advisory messages for those routines which can produce explicit output are both Fortran Unit 6. 4. Additional Services from NAG (a) Documentation The Windows 95/NT version of NAG Fortran Library TextWare, a hypertext version of the full Fortran Library manual, is bundled with this implementation. Note: SMP-specific documentation is included as a separate "chapter" at the end of the "book". Each NAG Fortran SMP Library site is provided with a printed copy of the NAG Fortran SMP Library Manual (which supplements the full NAG Fortran Library Manual). Additional SMP manuals and printed copies of the full Fortran Library manual are available at prices published in the NAG documentation order form. 5. Support from NAG (a) Contact with NAG Queries concerning this document or the implementation generally should be directed initially to your local Advisory Service. If you have difficulty in making contact locally, you can write to NAG directly, at one of the supplied addresses. Users subscribing to the support service are encouraged to contact one of the NAG Response Centres (see below). (b) NAG Response Centres The NAG Response Centres are available for general enquiries from all users and also for technical queries from sites with an annually licensed product or support service. The Response Centres are open during office hours, but contact is possible by fax, email and phone (answering machine) at all times. When contacting a Response Centre please quote your NAG user reference and NAG product code. (c) Network Network, NAG's newsletter, is produced periodically and sent free of charge to sites with a supported product or service. (d) NAG Website The NAG Website is an information service providing items of interest to users and prospective users of NAG products and services. The information is regularly updated and reviewed and includes implementation availability, descriptions of products, downloadable software and technical reports. The NAG Website can be accessed at http://www.nag.co.uk/ or http://www.nag.com/ (in the USA) 8. NAG Users Association NAGUA, the NAG Users Association, is a self-financing, non-profitmaking body. It exists to promote communications between NAG and users of its products and services. It provides information to NAG on the requirements of users, who are in turn kept informed of developments in services. Membership is available to any institution or individual holding a licence for any NAG product or service. Members receive discounts on the registration fees at conferences and workshops. For an information pack and membership application form, please contact NAGUA at the supplied address. Appendix - supplied addresses NAG Ltd Wilkinson House Jordan Hill Road OXFORD OX2 8DR NAG Ltd Response Centre United Kingdom email: support@nag.co.uk Tel: +44 1865 511245 Tel: +44 1865 311744 Fax: +44 1865 310139 Fax: +44 1865 310139 NAG Inc 1400 Opus Place, Suite 200 Downers Grove IL 60515-5702 NAG Inc Response Center USA email: infodesk@nag.com Tel: +1 630 971 2337 Tel: +1 630 971 2345 Fax: +1 630 971 2706 Fax: +1 630 971 2346 NAG Users Association PO Box 426 OXFORD OX2 8SD United Kingdom email: nagua@nag.co.uk Tel: +44 1865 311102 [NP3309/UN]