Users' Note(3NAG) Fortran Library Users' Note(3NAG) Name nag_fl_un - NAG Fortran Library, Mark 17, Users' Note NAG Fortran Library, Mark 17 FLSOL17DA Sun (SPARC) Solaris Double Precision Users' Note Introduction This document is essential reading for every user of the NAG Fortran Library Implementation specified in the title. It provides implementation-specific detail that augments the information provided in the NAG Fortran Library Manual and Introductory Guide. Wherever those manuals refer to the "Users' Note for your implementation", the user should consult this note. NAG recommends that users read the following minimum ref- erence material before calling any library routine: (a) Essential Introduction (b) Chapter Introduction (c) Routine Document (d) Implementation-specific Users' Note Items (a), (b) and (c) are included in the NAG Fortran Library Manual; items (a) and (b) are also included in the NAG Fortran Library Introductory Guide; item (d) is this document which is provided in man page form. Items (a) and (d) are also supplied on the distribution medium. Each NAG Fortran Library site is supplied with at least one copy of each of the above. Please ask your NAG Site Con- tact for further information. Availability of Routines All routines listed in the chapter contents documents of the NAG Fortran Library Manual, Mark 17 are available in this implementation. At Mark 17, 43 new primary ('user- callable') routines have been introduced, and 25 deleted. Please consult the document FORTRAN MARK 17 NEWS in the manual for lists of these routines and for a list of rou- tines scheduled for withdrawal at Mark 18 or later. The file doc/news supplied to your site on the library distri- bution medium (see the section "User Documentation" below) also gives an outline of the new material available. FLSOL17DA 04/03/96 1 Users' Note(3NAG) Fortran Library Users' Note(3NAG) General Information Accessing the Library Assuming that libnag.a has been installed in /usr/local/lib or /usr/lib, then a user may link to the NAG Fortran Library in the following manner: f77 -dalign driver.f -lnag where driver.f is the user's application program. If lib- nag.so.1 has been installed, then a user may link in the same manner. N.B. The -dalign flag MUST be used in all cases, as it was used to compile all library routines. Interpretation of Bold Italicised Terms For this double precision implementation, the bold itali- cised terms used in the NAG Fortran Library Manual (and shown here as //.....// ) should be interpreted as: //real// - DOUBLE PRECISION (REAL*8) //basic precision// - double precision //complex// - COMPLEX*16 //additional precision// - quadruple precision (REAL*16) //machine precision// - the machine precision, see the value returned by X02AJF in the section "Routine-specific Information" 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. In routine documents that have been newly typeset since Mark 12 additional bold italicised terms are used in the published example programs and they must be interpreted as follows: //real// as an intrinsic function name - DBLE //imag// - DIMAG //cmplx// - DCMPLX //conjg// - DCONJG //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 Equa- tions (LAPACK) and Chapter F08 - Least-squares and FLSOL17DA 04/03/96 2 Users' Note(3NAG) Fortran Library Users' Note(3NAG) 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 typeset examples 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 Example Programs In the NAG Fortran Library Manual, routine documents that have been typeset since Mark 12 present the example pro- grams in a generalised form, using bold italicised terms as described in the section "Interpretation of Bold Itali- cised Terms" above. In other routine documents, the example programs are in single precision and require modification for use with double precision routines. This conversion can entail: - Changing REAL or COMPLEX type specifications to REAL*8 or COMPLEX*16 - Changing certain intrinsic function references, e.g. REAL or FLOAT to DBLE, ALOG to DLOG, CMPLX to DCMPLX, and so on - Changing real constants to double precision form, e.g. 0.1 or 0.1E0 to 0.1D0 The example programs supplied to a site in machine- readable form have been modified as necessary so that they are suitable for immediate execution. Note that all the distributed example programs have been revised and do not correspond exactly with the programs published in the man- ual, unless the documents have been recently typeset. The distributed example programs should be used in preference wherever possible. The example programs are most easily accessed by the com- mand nagexample, which will provide you with a copy of an example program (and its data, if any), compile the pro- gram and link it with the library (showing you the compile command so that you can recompile your own version of the program). Finally, the executable program will be run, presenting its output to stdout. The example program con- cerned is specified by the argument to nagexample, which should be the name of a NAG Fortran Library routine, e.g. nagexample c02aff FLSOL17DA 04/03/96 3 Users' Note(3NAG) Fortran Library Users' Note(3NAG) will copy the example program and its data into the files c02affe.f and c02affe.d in the current directory and pro- cess them to produce the example program results. Explicit Output from NAG Routines Certain routines produce explicit error messages and advi- sory 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 the section "Routine-specific Information" below). The maximum record lengths of error messages and advisory messages (including carriage control characters) are 80 characters, except where otherwise specified. User Documentation The following information is provided in man page form: nag_fl_un.3 - Users' Note (this document) The following machine-readable information files are pro- vided by NAG on the library distribution medium. Please consult your local advisory service or NAG Site Contact for further details: essint - the Essential Introduction to the NAG Fortran Library summary - a brief summary of the routines news - an outline of the new and enhanced routines available at Mark 17 replaced - a list of routines available at earlier Marks of the Library but since withdrawn, together with recommended replacements 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 See the section "Additional Services from NAG" below for additional documentation available from NAG. Routine-specific Information Any further information which applies to one or more rou- tines in this implementation is listed below, chapter by chapter. (a) F06, F07 and F08 In the libnag-spl.a library, calls to all the Basic Linear Algebra Subprograms (BLAS) and linear algebra routines (LAPACK) are implemented by calls to the Sun Performance Library. FLSOL17DA 04/03/96 4 Users' Note(3NAG) Fortran Library Users' Note(3NAG) (b) G02 The value of ACC, the machine-dependent constant mentioned in several documents in the chapter, is 1.0D-13. (c) P01 On hard failure, P01ABF writes the error message to the error message unit specified by X04AAF and then stops. (d) S07 - S21 The constants referred to in the NAG Fortran Library Man- ual have the following values in this implementation: S07AAF F(1) = 1.0D+13 F(2) = 1.0D-14 S10AAF E(1) = 18.50 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 FLSOL17DA 04/03/96 5 Users' Note(3NAG) Fortran Library Users' Note(3NAG) 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 (e) X01 The values of the mathematical constants are: X01AAF (PI) = 3.1415926535897932 X01ABF (GAMMA) = 0.5772156649015329 (f) 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 ) FLSOL17DA 04/03/96 6 Users' Note(3NAG) Fortran Library Users' Note(3NAG) X02ANF = Z'0010000000000000' ( 2.22507385850721D-308 ) Parameters of other aspects of the computing environment X02AHF = Z'4950000000000000' ( 1.42724769270596D+45 ) X02BBF = 2147483647 X02BEF = 15 X02DAF = .FALSE. (g) X04 The default output units for error and advisory messages for those routines which can produce explicit output are Fortran Units 0 and 6, respectively. (h) X05 The finest granularity of wall-clock time available on this system is one second, so the seventh element of the integer array passed as a parameter to X05AAF will always be returned with the value 0. Additional Services from NAG (a) Printed Manuals Where a manual has been provided as part of the contract issue, this manual is updated automatically at each new release of the software, by the supply of a manual update set or a complete new manual. If additional manuals have been ordered in the past then updates to these manuals may be ordered separately. They are NOT sent automatically. Additional complete manuals and the manual updates (where relevant) are available at prices published in the NAG documentation order form. (b) On-line Information Supplement To complement the manuals NAG produces an On-line Informa- tion Supplement which fulfils two roles: - it gives keyword-driven guidance on the selection of the appropriate NAG routine - it gives abbreviated on-line documentation of the NAG routines, to enable the user to call the routines and investigate any IFAIL messages without recourse to the manual Support from NAG (a) Contact with NAG Queries concerning this document or the implementation generally should be directed initially to your local Advi- sory Service. If you have difficulty in making contact FLSOL17DA 04/03/96 7 Users' Note(3NAG) Fortran Library Users' Note(3NAG) locally, you can write to NAG directly, at one of the sup- plied 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 quarterly and sent free of charge to sites with a supported product or ser- vice. (d) NAG Bulletin Board The NAG Bulletin Board 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 avail- ability, descriptions of products, downloadable software and technical reports. The bulletin board can be contacted using Gopher Host=www.nag.co.uk, Port=70, Type=1, Path=1/ or WWW http://www.nag.co.uk/ or http://www.nag.com/ (in the USA) NAG Users Association NAGUA, the NAG Users Association, is a self-financing, non-profitmaking body. It exists to promote communica- tions 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 ser- vice. FLSOL17DA 04/03/96 8 Users' Note(3NAG) Fortran Library Users' Note(3NAG) Members receive discounts on the registration fees at con- ferences 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: infodesk@nag.co.uk Tel: +44 1865 511245 Tel: +44 1865 311744 Fax: +44 1865 310139 Fax: +44 1865 311755 NAG Inc 1400 Opus Place, Suite 200 Downers Grove IL 60515-5702 NAG Inc Response Center USA email: infodesk@nag.com Tel: +1 708 971 2337 Tel: +1 708 971 2345 Fax: +1 708 971 2706 Fax: +1 708 971 2346 NAG GmbH Schleissheimerstrasse 5 D-85748 Garching Germany Tel: +49 89 3207395 Fax: +49 89 3207396 NAG Users Association PO Box 426 OXFORD OX2 8SD United Kingdom email: nagua@nag.co.uk Tel: +44 1865 311102 FLSOL17DA 04/03/96 9