From ab8cc85adde879fb963c94d15675783f2cf4b183 Mon Sep 17 00:00:00 2001 From: dos-reis Date: Tue, 14 Aug 2007 05:14:52 +0000 Subject: Initial population. --- src/hyper/pages/nagx.ht | 1510 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1510 insertions(+) create mode 100644 src/hyper/pages/nagx.ht (limited to 'src/hyper/pages/nagx.ht') diff --git a/src/hyper/pages/nagx.ht b/src/hyper/pages/nagx.ht new file mode 100644 index 00000000..0676bfe3 --- /dev/null +++ b/src/hyper/pages/nagx.ht @@ -0,0 +1,1510 @@ +\begin{page}{manpageXXx01}{NAG On-line Documentation: x01} +\beginscroll +\begin{verbatim} + + + + X01(3NAG) Foundation Library (12/10/92) X01(3NAG) + + + + X01 -- Mathematical Constants Introduction -- X01 + Chapter X01 + Mathematical Constants + + 1. Scope of the Chapter + + This chapter is concerned with the provision of mathematical + constants required by other routines within the Library. + + It should be noted that because of the trivial nature of the + routines individual routine documents are not provided. + + 2. Background to the Problems + + Some Library routines require mathematical constants to maximum + machine precision. These routines call Chapter X01 and thus + lessen the number of changes that have to be made between + different implementations of the Library. + + 3. Recommendations on Choice and Use of Routines + + Although these routines are primarily intended for use by other + routines they may be accessed directly by the user: + + Constant Fortran Specification + + (pi) DOUBLE PRECISION FUNCTION X01AAF(X) + DOUBLE PRECISION X + + (gamma) DOUBLE PRECISION FUNCTION X01ABF(X) + (Euler constant) DOUBLE PRECISION X + + The argument X of these routines is a dummy argument. + + + X01 -- Mathematical Constants Contents -- X01 + Chapter X01 + + Mathematical Constants + + X01AAF (pi) + + X01ABF Euler's constant, (gamma) + +\end{verbatim} +\endscroll +\end{page} +\begin{page}{manpageXXx02}{NAG On-line Documentation: x02} +\beginscroll +\begin{verbatim} + + + + X02(3NAG) Foundation Library (12/10/92) X02(3NAG) + + + + X02 -- Machine Constants Introduction -- X02 + Chapter X02 + Machine Constants + + 1. Scope of the Chapter + + This chapter is concerned with parameters which characterise + certain aspects of the computing environment in which the NAG + Foundation Library is implemented. They relate primarily to + floating-point arithmetic, but also to integer arithmetic and the + elementary functions. The values of the parameters vary from one + implementation of the Library to another, but within the context + of a single implementation they are constants. + + The parameters are intended for use primarily by other routines + in the Library, but users of the Library may sometimes need to + refer to them directly. + + Each parameter-value is returned by a separate Fortran function. + Because of the trivial nature of the functions, individual + routine documents are not provided; the necessary details are + given in Section 3 of this Introduction. + + 2. Background to the Problems + + 2.1. Floating-Point Arithmetic + + 2.1.1. A model of floating-point arithmetic + + In order to characterise the important properties of floating- + point arithmetic by means of a small number of parameters, NAG + uses a simplified model of floating-point arithmetic. The + parameters of the model can be chosen to provide a sufficiently + close description of the behaviour of actual implementations of + floating-point arithmetic, but not, in general, an exact + description; actual implementations vary too much in the details + of how numbers are represented or arithmetic operations are + performed. + + The model is based on that developed by Brown [1], but differs in + some respects. The essential features are summarised here. + + The model is characterised by four integer parameters and one + logical parameter. The four integer parameters are: + + b : the base + + p : the precision (i.e. the number of significant base-B + digits) + + e : the minimum exponent + min + + e : the maximum exponent + max + + These parameters define a set of numerical values of the form: + + e + f*b + + where the exponent e must lie in the range [e ,e ], and the + min max + fraction f (also called the mantissa or significand) lies in the + range [1/b,1), and may be written: + + f=0.f f ...f + 1 2 p + + Thus f is a p-digit fraction to the base b; the f are the base-b + i + digits of the fraction: they are integers in the range 0 to b-1, + and the leading digit f must not be zero. + 1 + + The set of values so defined (together with zero) are called + model numbers. For example, if b=10, p=5, e =-99 and e =+99, + min max + 67 + then a typical model number is 0.12345*10 . + + The model numbers must obey certain rules for the computed + results of the following basic arithmetic operations: addition, + subtraction, multiplication, negation, absolute value, and + comparisons. The rules depend on the value of the logical + parameter ROUNDS. + + If ROUNDS is true, then the computed result must be the nearest + model number to the exact result (assuming that overflow or + underflow does not occur); if the exact result is midway between + two model numbers, then it may be rounded either way. + + If ROUNDS is false, then: if the exact result is a model number, + the computed result must be equal to the exact result; otherwise, + the computed result may be either of the adjacent model numbers + on either side of the exact result. + + For division and square root, this latter rule is further relaxed + (regardless of the value of ROUNDS): the computed result may also + be one of the next adjacent model numbers on either side of the + permitted values just stated. + + On some machines, the full set of representable floating-point + numbers conforms to the rules of the model with appropriate + values of b, p, e , e and ROUNDS. For example, for machines + min max + with IEEE arithmetic, in double precision: + + b = 2 + + p = 53 + + e =-1021 + min + + e =1024 and ROUNDS is true. + max + + For other machines, values of the model parameters must be chosen + which define a large subset of the representable numbers; + typically it may be necessary to decrease p by 1 (in which case + ROUNDS is always set to false), or to increase e or decrease + min + e by a little bit. There are additional rules to ensure that + max + arithmetic operations on those representable numbers which are + not model numbers, are consistent with arithmetic on model + numbers. + + (Note: the model used here differs from that described in Brown + [1] in the following respects: square-root is treated, like + division, as a weakly supported operator; and the logical + parameter ROUNDS has been introduced to take account of machines + with good rounding.) + + 2.1.2. Derived parameters of floating-point arithmetic + + Most numerical algorithms require access, not to the basic + parameters of the model, but to certain derived values, of which + the most important are: + + (1) 1-p + the machine precision = (-)*b if ROUNDS is true, + (epsilon): (2) + + 1-p + = b otherwise (but see Note below). + + e -1 + min + the smallest positive = b + model number: + + e + -p max + the largest positive = (1-b )*b + model number: + + Note: this value is increased very slightly in some + implementations to ensure that the computed result of 1+(epsilon) + or 1-(epsilon) differs from 1. For example in IEEE binary single + -24 -47 + precision arithmetic the value is set to 2 +2 . + + Two additional derived values are used in the NAG Foundation + Library. Their definitions depend not only on the properties of + the basic arithmetic operations just considered, but also on + properties of some of the elementary functions. We define the + safe range parameter to be the smallest positive model number z + such that for any x in the range [z,1/z] the following can be + computed without undue loss of accuracy, overflow, underflow or + other error: + + -x + + 1/x + + -1/x + + SQRT(x) + + LOG(x) + + EXP(LOG(x)) + + y**(LOG(x)/LOG(y)) for any y + + In a similar fashion we define the safe range parameter for + complex arithmetic as the smallest positive model number z such + that for any x in the range [z,1/z] the following can be computed + without any undue loss of accuracy, overflow, underflow or other + error: + + -w + + 1/w + + -1/w + + SQRT(w) + + LOG(w) + + EXP(LOG(w)) + + y**(LOG(w)/LOG(y)) for any y + + ABS(w) + + where w is any of x, ix, x+ix, 1/x, i/x, 1/x+i/x, and i is the + square root of -1. + + This parameter was introduced to take account of the quality of + complex arithmetic on the machine. On machines with well + implemented complex arithmetic, its value will differ from that + of the real safe range parameter by a small multiplying factor + less than 10. For poorly implemented complex arithmetic this + factor may be larger by many orders of magnitude. + + 2.2. Other Aspects of the Computing Environment + + No attempt has been made to characterise comprehensively any + other aspects of the computing environment. The other functions + in this chapter provide specific information that is occasionally + required by routines in the Library. + + 2.3. References + + [1] Brown W S (1981) A Simple but Realistic Model of Floating- + point Computation. ACM Trans. Math. Softw. 7 445--480. + + 3. Recommendations on Choice and Use of Routines + + 3.1. Parameters of Floating-point Arithmetic + + DOUBLE PRECISION FUNCTION returns the machine precision i.e. + X02AJF() (1) 1-p 1-p + (-)*b if ROUNDS is true or b + (2) + otherwise (or a value very slightly + larger than this, see Section 2.1.2) + + DOUBLE PRECISION FUNCTION returns the smallest positive model + X02AKF() e -1 + min + number i.e. b + + DOUBLE PRECISION FUNCTION returns the largest positive model + X02ALF() e + -p max + number i.e. (1-b )*b + + + DOUBLE PRECISION FUNCTION returns the safe range parameter as + X02AMF() defined in Section 2.1.2 + + DOUBLE PRECISION FUNCTION returns the safe range parameter for + X02ANF() complex arithmetic as defined in + Section 2.1.2 + + INTEGER FUNCTION X02BHF() returns the model parameter b + + INTEGER FUNCTION X02BJF() returns the model parameter p + + INTEGER FUNCTION X02BKF() returns the model parameter e + min + + INTEGER FUNCTION X02BLF() returns the model parameter e + max + + LOGICAL FUNCTION X02DJF() returns the model parameter ROUNDS + + 3.2. Parameters of Other Aspects of the Computing Environment + + DOUBLE PRECISION FUNCTION returns the largest positive real + X02AHF(X) argument for which the SIN and COS + DOUBLE PRECISION X routines return a result with some + meaningful accuracy + + INTEGER FUNCTION X02BBF returns the largest positive integer + (X) value + DOUBLE PRECISION X + + INTEGER FUNCTION X02BEF returns the maximum number of decimal + (X) digits which can be accurately + DOUBLE PRECISION X represented over the whole range of + floating-point numbers + + The argument X of these routines is a dummy argument. + + 4. Example Program Text + + The example program simply prints the values of all the functions + in Chapter X02. Obviously the results will vary from one + implementation of the Library to another. + + + X02 -- Machine Constants Contents -- X02 + Chapter X02 + + Machine Constants + + X02AHF Largest permissible argument for SIN and COS + + X02AJF Machine precision + + X02AKF Smallest positive model number + + X02ALF Largest positive model number + + X02AMF Safe range of floating-point arithmetic + + X02ANF Safe range of complex floating-point arithmetic + + X02BBF Largest representable integer + + X02BEF Maximum number of decimal digits that can be represented + + X02BHF Parameter of floating-point arithmetic model, b + + X02BJF Parameter of floating-point arithmetic model, p + + X02BKF Parameter of floating-point arithmetic model, e + min + + X02BLF Parameter of floating-point arithmetic model, e + max + + X02DJF Parameter of floating-point arithmetic model, ROUNDS + +\end{verbatim} +\endscroll +\end{page} +\begin{page}{manpageXXx04}{NAG On-line Documentation: x04} +\beginscroll +\begin{verbatim} + + + + X04(3NAG) Foundation Library (12/10/92) X04(3NAG) + + + + X04 -- Input/Output Utilities Introduction -- X04 + Chapter X04 + Input/Output Utilities + + 1. Scope of the Chapter + + This chapter contains utility routines concerned with input and + output to or from an external file. + + 2. Background to the Problems + + 2.1. Output from NAG Foundation Library Routines + + Output from NAG Foundation Library routines to an external file + falls into two categories: + + (a) Error messages which are always associated with an error + exit from a routine, that is, with a non-zero value of + IFAIL as specified in Section 6 of the routine document. + + (b) Advisory messages which include output of final results, + output of intermediate results to monitor the course of a + computation, and various warning or informative messages. + + Each category of output is written to its own Fortran output unit + - the error message unit or the advisory message unit. In + practice these may be the same unit number. Default unit numbers + are provided for each implementation of the Library (see the + Users' Note); they may be changed by users. Output of error + messages may be controlled by the setting of IFAIL (see the + Essential Introduction). Output of advisory messages may usually + be controlled by the setting of some other parameter (e.g. + MSGLVL) (or in some routines also by IFAIL). An alternative + mechanism for completely suppressing output is to set the + relevant unit number < 0. + + For further information about error and advisory messages, see + Chapter P01. + + 2.2. Matrix Printing Routines + + Routines are provided to allow formatted output of general + rectangular or triangular matrices stored in a two-dimensional + array (real and complex data types). + + All output is directed to the unit number for output of advisory + messages, which may be altered by a call to X04ABF. + + 3. Recommendations on Choice and Use of Routines + + Apart from the obvious utility of the matrix printing routines, + users of the Library may need to call routines in Chapter X04 for + the following purposes: + + if the default unit number for error messages (given in the + Users' Note for your implementation) is not satisfactory, + it may be changed to a new value NERR by the statement + + CALL X04AAF(1,NERR) + + Similarly the unit number for advisory messages may be + changed to a new value NADV by the statement + + CALL X04ABF(1,NADV) + + 4. Index + + Accessing unit number: + of advisory message unit X04ABF + of error message unit X04AAF + Printing matrices: + general complex matrix X04DAF + general real matrix X04CAF + + + + X04 -- Input/Output Utilities Contents -- X04 + Chapter X04 + + Input/Output Utilities + + X04AAF Return or set unit number for error messages + + X04ABF Return or set unit number for advisory messages + + X04CAF Print a real general matrix + + X04DAF Print a complex general matrix + +\end{verbatim} +\endscroll +\end{page} +\begin{page}{manpageXXx04aaf}{NAG On-line Documentation: x04aaf} +\beginscroll +\begin{verbatim} + + + + X04AAF(3NAG) Foundation Library (12/10/92) X04AAF(3NAG) + + + + X04 -- Input/Output Utilities X04AAF + X04AAF -- NAG Foundation Library Routine Document + + Note: Before using this routine, please read the Users' Note for + your implementation to check implementation-dependent details. + The symbol (*) after a NAG routine name denotes a routine that is + not included in the Foundation Library. + + 1. Purpose + + X04AAF returns the value of the current error message unit + number, or sets the current error message unit number to a new + value. + + 2. Specification + + SUBROUTINE X04AAF (IFLAG, NERR) + INTEGER IFLAG, NERR + + 3. Description + + This routine enables those library routines which output error + messages, to determine the number of the output unit to which the + error messages are to be sent; in this case X04AAF is called with + IFLAG = 0. X04AAF may also be called with IFLAG = 1 to set the + unit number to a specified value. Otherwise a default value + (stated in the Users' Note for your implementation) is returned. + + Records written to this output unit by other library routines are + at most 80 characters long (including a line-printer carriage + control character). + + Note that if the unit number is set < 0, no messages will be + output. + + 4. References + + None. + + 5. Parameters + + 1: IFLAG -- INTEGER Input + On entry: the action to be taken (see NERR). Constraint: + IFLAG = 0 or 1. + + 2: NERR -- INTEGER Input/Output + On entry: + if IFLAG = 0, NERR need not be set; + + if IFLAG = 1, NERR must specify the new error message + unit number. + On exit: + if IFLAG = 0, NERR is set to the current error message + unit number, + + if IFLAG = 1, NERR is unchanged. + Note that Fortran unit numbers must be positive or zero. If + NERR is set < 0, output of error messages is totally + suppressed. + + 6. Error Indicators and Warnings + + None. + + 7. Accuracy + + Not applicable. + + 8. Further Comments + + The time taken by the routine is negligible. + + 9. Example + + In this example X04AAF is called by the user's main program to + make the error message from the routine DUMMY appear on the same + unit as the rest of the output (unit 6). Normally a NAG + Foundation Library routine with an IFAIL parameter (see Essential + Introduction) would take the place of DUMMY. + + The example program is not reproduced here. The source code for + all example programs is distributed with the NAG Foundation + Library software and should be available on-line. +\end{verbatim} +\endscroll +\end{page} +\begin{page}{manpageXXx04abf}{NAG On-line Documentation: x04abf} +\beginscroll +\begin{verbatim} + + + + X04ABF(3NAG) Foundation Library (12/10/92) X04ABF(3NAG) + + + + X04 -- Input/Output Utilities X04ABF + X04ABF -- NAG Foundation Library Routine Document + + Note: Before using this routine, please read the Users' Note for + your implementation to check implementation-dependent details. + The symbol (*) after a NAG routine name denotes a routine that is + not included in the Foundation Library. + + 1. Purpose + + X04ABF returns the value of the current advisory message unit + number, or sets the current advisory message unit number to a new + value. + + 2. Specification + + SUBROUTINE X04ABF (IFLAG, NADV) + INTEGER IFLAG, NADV + + 3. Description + + This routine enables those library routines which output advisory + messages, to determine the number of the output unit to which the + advisory messages are to be sent; in this case X04ABF is called + with IFLAG = 0. X04ABF may also be called with IFLAG = 1 to set + the unit number to a specified value. Otherwise a default value + (stated in the User's Note for your implementation) is returned. + + Records written to this output unit by other library routines are + at most 120 characters long (including a line-printer carriage + control character), unless those library routines allow users to + specify longer records. + + Note that if the unit number is set < 0, no messages will be + output. + + 4. References + + None. + + 5. Parameters + + 1: IFLAG -- INTEGER Input + On entry: the action to be taken (see NADV). Constraint: + IFLAG = 0 or 1. + + 2: NADV -- INTEGER Input/Output + On entry: + if IFLAG = 0, NADV need not be set; + + if IFLAG = 1, NADV must specify the new advisory + message unit number. + On exit: + if IFLAG = 0, NADV is set to the current advisory + message unit number; + + if IFLAG = 1, NADV is unchanged. + Note that Fortran unit numbers must be positive or zero. If + NADV is set < 0, output of advisory messages is totally + suppressed. + + 6. Error Indicators and Warnings + + None. + + 7. Accuracy + + Not applicable. + + 8. Further Comments + + The time taken by this routine is negligible. + + 9. Example + + In this example X04ABF is called by the user's main program to + make the advisory message from the routine DUMMY appear on the + same unit as the rest of the output (unit 6). Normally a NAG + Foundation Library routine with an IFAIL parameter (see Essential + Introduction) would take the place of DUMMY. + + The example program is not reproduced here. The source code for + all example programs is distributed with the NAG Foundation + Library software and should be available on-line. +\end{verbatim} +\endscroll +\end{page} +\begin{page}{manpageXXx04caf}{NAG On-line Documentation: x04caf} +\beginscroll +\begin{verbatim} + + + + X04CAF(3NAG) Foundation Library (12/10/92) X04CAF(3NAG) + + + + X04 -- Input/Output Utilities X04CAF + X04CAF -- NAG Foundation Library Routine Document + + Note: Before using this routine, please read the Users' Note for + your implementation to check implementation-dependent details. + The symbol (*) after a NAG routine name denotes a routine that is + not included in the Foundation Library. + + 1. Purpose + + X04CAF is an easy-to-use routine to print a real matrix stored in + a two-dimensional array. + + 2. Specification + + SUBROUTINE X04CAF (MATRIX, DIAG, M, N, A, LDA, TITLE, + 1 IFAIL) + INTEGER M, N, LDA, IFAIL + DOUBLE PRECISION A(LDA,*) + CHARACTER*1 MATRIX, DIAG + CHARACTER*(*) TITLE + + 3. Description + + X04CAF prints a real matrix. It is an easy-to-use driver for + X04CBF(*). The routine uses default values for the format in + which numbers are printed, for labelling the rows and columns, + and for output record length. + + X04CAF will choose a format code such that numbers will be + printed with either an F8.4, F11.4 or a 1PE13.4 format. The F8.4 + code is chosen if the sizes of all the matrix elements to be + printed lie between 0.001 and 1.0. The F11.4 code is chosen if + the sizes of all the matrix elements to be printed lie between 0. + 001 and 9999.9999. Otherwise the 1PE13.4 code is chosen. + + The matrix is printed with integer row and column labels, and + with a maximum record length of 80. + + The matrix is output to the unit defined by X04ABF. + + 4. References + + None. + + 5. Parameters + + 1: MATRIX -- CHARACTER*1 Input + On entry: indicates the part of the matrix to be printed, as + follows: + + MATRIX = 'G' (General), the whole of the rectangular matrix. + + MATRIX = 'L' (Lower), the lower triangle of the matrix, or + the lower trapezium if the matrix has more rows than + columns. + + MATRIX = 'U' (Upper), the upper triangle of the matrix, or + the upper trapezium if the matrix has more columns than + rows. Constraint: MATRIX must be one of 'G', 'L' or 'U'. + + 2: DIAG -- CHARACTER*1 Input + On entry: unless MATRIX = 'G', DIAG must specify whether the + diagonal elements of the matrix are to be printed, as + follows: + + DIAG = 'B' (Blank), the diagonal elements of the matrix are + not referenced and not printed. + + DIAG = 'U' (Unit diagonal), the diagonal elements of the + matrix are not referenced, but are assumed all to be unity, + and are printed as such. + + DIAG = 'N' (Non-unit diagonal), the diagonal elements of the + matrix are referenced and printed. + + If MATRIX = 'G', then DIAG need not be set. Constraint: If + MATRIX /= 'G', then DIAG must be one of 'B', 'U' or 'N'. + + 3: M -- INTEGER Input + + 4: N -- INTEGER Input + On entry: the number of rows and columns of the matrix, + respectively, to be printed. + + If either of M or N is less than 1, X04CAF will exit + immediately after printing TITLE; no row or column labels + are printed. + + 5: A(LDA,*) -- DOUBLE PRECISION array Input + Note: the second dimension of the array A must be at least + max(1,N). + On entry: the matrix to be printed. Only the elements that + will be referred to, as specified by parameters MATRIX and + DIAG, need be set. + + 6: LDA -- INTEGER Input + On entry: + the first dimension of the array A as declared in the + (sub)program from which X04CAF is called. + Constraint: LDA >= M. + + 7: TITLE -- CHARACTER*(*) Input + On entry: a title to be printed above the matrix. If TITLE = + ' ', no title (and no blank line) will be printed. + + If TITLE contains more than 80 characters, the contents of + TITLE will be wrapped onto more than one line, with the + break after 80 characters. + + Any trailing blank characters in TITLE are ignored. + + 8: IFAIL -- INTEGER Input/Output + On entry: IFAIL must be set to 0, -1 or 1. For users not + familiar with this parameter (described in the Essential + Introduction) the recommended value is 0. + + On exit: IFAIL = 0 unless the routine detects an error (see + Section 6). + + 6. Error Indicators and Warnings + + Errors detected by the routine: + + If on entry IFAIL = 0 or -1, explanatory error messages are + output on the current error message unit (as defined by X04AAF). + + IFAIL= 1 + On entry MATRIX /= 'G', 'L' or 'U'. + + IFAIL= 2 + On entry MATRIX = 'L' or 'U', but DIAG /= 'N', 'U' or 'B'. + + IFAIL= 3 + On entry LDA < M. + + 7. Accuracy + + Not applicable. + + 8. Further Comments + + A call to X04CAF is equivalent to a call to X04CBF(*) with the + following argument values: + + + NCOLS = 80 + INDENT = 0 + LABROW = 'I' + LABCOL = 'I' + FORMAT = ' ' + + + 9. Example + + This example program calls X04CAF twice, first to print a 3 by 5 + rectangular matrix, and then to print a 5 by 5 lower triangular + matrix. + + The example program is not reproduced here. The source code for + all example programs is distributed with the NAG Foundation + Library software and should be available on-line. + +\end{verbatim} +\endscroll +\end{page} +\begin{page}{manpageXXx04daf}{NAG On-line Documentation: x04daf} +\beginscroll +\begin{verbatim} + + + + X04DAF(3NAG) Foundation Library (12/10/92) X04DAF(3NAG) + + + + X04 -- Input/Output Utilities X04DAF + X04DAF -- NAG Foundation Library Routine Document + + Note: Before using this routine, please read the Users' Note for + your implementation to check implementation-dependent details. + The symbol (*) after a NAG routine name denotes a routine that is + not included in the Foundation Library. + + 1. Purpose + + X04DAF is an easy-to-use routine to print a complex matrix stored + in a two-dimensional array. + + 2. Specification + + SUBROUTINE X04DAF (MATRIX, DIAG, M, N, A, LDA, TITLE, + 1 IFAIL) + INTEGER M, N, LDA, IFAIL + COMPLEX(KIND(1.0D0)) A(LDA,*) + CHARACTER*1 MATRIX, DIAG + CHARACTER*(*) TITLE + + 3. Description + + X04DAF prints a complex matrix. It is an easy-to-use driver for + X04DBF(*). The routine uses default values for the format in + which numbers are printed, for labelling the rows and columns, + and for output record length. + + X04DAF will choose a format code such that numbers will be + printed with either an F8.4, F11.4 or a 1PE13.4 format. The F8.4 + code is chosen if the sizes of all the matrix elements to be + printed lie between 0.001 and 1.0. The F11.4 code is chosen if + the sizes of all the matrix elements to be printed lie between 0. + 001 and 9999.9999. Otherwise the 1PE13.4 code is chosen. The + chosen code is used to print each complex element of the matrix + with the real part above the imaginary part. + + The matrix is printed with integer row and column labels, and + with a maximum record length of 80. + + The matrix is output to the unit defined by X04ABF. + + 4. References + + None. + + 5. Parameters + + 1: MATRIX -- CHARACTER*1 Input + On entry: indicates the part of the matrix to be printed, as + follows: + + MATRIX = 'G' (General), the whole of the rectangular matrix. + + MATRIX = 'L' (Lower), the lower triangle of the matrix, or + the lower trapezium if the matrix has more rows than + columns. + + MATRIX = 'U' (Upper), the upper triangle of the matrix, or + the upper trapezium if the matrix has more columns than + rows. Constraint: MATRIX must be one of 'G', 'L' or 'U'. + + 2: DIAG -- CHARACTER*1 Input + On entry: unless MATRIX = 'G', DIAG must specify whether the + diagonal elements of the matrix are to be printed, as + follows: + + DIAG = 'B' (Blank), the diagonal elements of the matrix are + not referenced and not printed. + + DIAG = 'U' (Unit diagonal), the diagonal elements of the + matrix are not referenced, but are assumed all to be unity, + and are printed as such. + + DIAG = 'N' (Non-unit diagonal), the diagonal elements of the + matrix are referenced and printed. + + If MATRIX = 'G', then DIAG need not be set. Constraint: If + MATRIX /= 'G', then DIAG must be one of 'B', 'U' or 'N'. + + 3: M -- INTEGER Input + + 4: N -- INTEGER Input + On entry: the number of rows and columns of the matrix, + respectively, to be printed. + + If either of M or N is less than 1, X04DAF will exit + immediately after printing TITLE; no row or column labels + are printed. + + 5: A(LDA,*) -- COMPLEX(KIND(1.0D)) array Input + Note: the second dimension of the array A must be at least + max(1,N). + On entry: the matrix to be printed. Only the elements that + will be referred to, as specified by parameters MATRIX and + DIAG, need be set. + + 6: LDA -- INTEGER Input + On entry: + the first dimension of the array A as declared in the + (sub)program from which X04DAF is called. + Constraint: LDA >= M. + + 7: TITLE -- CHARACTER*(*) Input + + On entry: a title to be printed above the matrix. If TITLE = + ' ', no title (and no blank line) will be printed. + + If TITLE contains more than 80 characters, the contents of + TITLE will be wrapped onto more than one line, with the + break after 80 characters. + + Any trailing blank characters in TITLE are ignored. + + 8: IFAIL -- INTEGER Input/Output + On entry: IFAIL must be set to 0, -1 or 1. For users not + familiar with this parameter (described in the Essential + Introduction) the recommended value is 0. + + On exit: IFAIL = 0 unless the routine detects an error (see + Section 6). + + 6. Error Indicators and Warnings + + Errors detected by the routine: + + If on entry IFAIL = 0 or -1, explanatory error messages are + output on the current error message unit (as defined by X04AAF). + + IFAIL= 1 + On entry MATRIX /= 'G', 'L' or 'U'. + + IFAIL= 2 + On entry MATRIX = 'L' or 'U', but DIAG /= 'N', 'U' or 'B'. + + IFAIL= 3 + On entry LDA < M. + + 7. Accuracy + + Not applicable. + + 8. Further Comments + + A call to X04DAF is equivalent to a call to X04DBF(*) with the + following argument values: + + + NCOLS = 80 + INDENT = 0 + LABROW = 'I' + LABCOL = 'I' + FORMAT = ' ' + USEFRM = 'A' + + + 9. Example + + This example program calls X04DAF twice, first to print a 4 by 3 + rectangular matrix, and then to print a 4 by 4 lower triangular + matrix. + + The example program is not reproduced here. The source code for + all example programs is distributed with the NAG Foundation + Library software and should be available on-line. + + +\end{verbatim} +\endscroll +\end{page} +\begin{page}{manpageXXx05}{NAG On-line Documentation: x05} +\beginscroll +\begin{verbatim} + + + + X05(3NAG) Foundation Library (12/10/92) X05(3NAG) + + + + X05 -- Date and Time Utilities Introduction -- X05 + Chapter X05 + Date and Time Utilities + + 1. Scope of the Chapter + + This chapter provides routines to obtain the current real time, + and the amount of processor time used. + + 2. Background to the Problems + + 2.1. Real Time + + Routines are provided to obtain the current time in two different + formats, and to compare two such times. + + 2.2. Processor Time + + A routine is provided to return the current amount of processor + time used. This allows the timing of a particular routine or + section of code. + + 3. Recommendations on Choice and Use of Routines + + X05AAF returns the current date/time in integer format. + + X05ABF converts from integer to character string date/time. + + X05ACF compares two date/time character strings. + + X05BAF returns the amount of processor time used. + + + X05 -- Date and Time Utilities Contents -- X05 + Chapter X05 + + Date and Time Utilities + + X05AAF Return date and time as an array of integers + + X05ABF Convert array of integers representing date and time to + character string + + X05ACF Compare two character strings representing date and time + + X05BAF Return the CPU time + +\end{verbatim} +\endscroll +\end{page} +\begin{page}{manpageXXx05aaf}{NAG On-line Documentation: x05aaf} +\beginscroll +\begin{verbatim} + + + + X05AAF(3NAG) Foundation Library (12/10/92) X05AAF(3NAG) + + + + X05 -- Date and Time Utilities X05AAF + X05AAF -- NAG Foundation Library Routine Document + + Note: Before using this routine, please read the Users' Note for + your implementation to check implementation-dependent details. + The symbol (*) after a NAG routine name denotes a routine that is + not included in the Foundation Library. + + 1. Purpose + + X05AAF returns the current date and time. + + 2. Specification + + SUBROUTINE X05AAF (ITIME) + INTEGER ITIME(7) + + 3. Description + + X05AAF returns the current date and time as a set of seven + integers. + + 4. References + + None. + + 5. Parameters + + 1: ITIME(7) -- INTEGER array Output + On exit: the current date and time, as follows: + + ITIME(1) contains the current year. + + ITIME(2) contains the current month, in the range 1--12. + + ITIME(3) contains the current day, in the range 1--31. + + ITIME(4) contains the current hour, in the range 0--23. + + ITIME(5) contains the current minute, in the range 0--59. + + ITIME(6) contains the current second, in the range 0--59. + + ITIME(7) contains the current millisecond, in the range 0-- + 999. + + 6. Error Indicators and Warnings + + None. + + 7. Accuracy + + The accuracy of this routine depends on the accuracy of the host + machine. In particular, on some machines it may not be possible + to return a value for the current millisecond, for example. In + this case, the value returned will be zero. + + 8. Further Comments + + None. + + 9. Example + + This program prints out the vector ITIME after a call to X05AAF. + + The example program is not reproduced here. The source code for + all example programs is distributed with the NAG Foundation + Library software and should be available on-line. +\end{verbatim} +\endscroll +\end{page} +\begin{page}{manpageXXx05abf}{NAG On-line Documentation: x05abf} +\beginscroll +\begin{verbatim} + + + + X05ABF(3NAG) Foundation Library (12/10/92) X05ABF(3NAG) + + + + X05 -- Date and Time Utilities X05ABF + X05ABF -- NAG Foundation Library Routine Document + + Note: Before using this routine, please read the Users' Note for + your implementation to check implementation-dependent details. + The symbol (*) after a NAG routine name denotes a routine that is + not included in the Foundation Library. + + 1. Purpose + + X05ABF converts from a seven-integer format time and date, as + returned by X05AAF, into a character string, returned via the + routine name. + + 2. Specification + + CHARACTER*30 FUNCTION X05ABF (ITIME) + INTEGER ITIME(7) + + 3. Description + + X05ABF returns a character string of length 30 which contains the + date and time as supplied in argument ITIME. On exit, the + character string has the following format: + + + `DAY XXTH MTH YEAR HR:MN:SC.MIL', + + + where DAY is one of 'Sun', 'Mon', 'Tue', 'Wed', 'Thu', + 'Fri', 'Sat', + + XX is an integer denoting the day of the month, + + TH is one of 'st', 'nd', 'rd', 'th', + + MTH is one of 'Jan', 'Feb', 'Mar', 'Apr', 'May', + 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec', + + YEAR is the year as a four digit integer, + + HR is the hour, + + MN is the minute, + + SC is the second, + + MIL is the millisecond. + + If on entry the date in ITIME is invalid, the string returned is + + 4. References + + None. + + 5. Parameters + + 1: ITIME(7) -- INTEGER array Input + On entry: a date and time in the format returned by X05AAF, + as follows: + ITIME must contain the year as a positive integer. + (1) + + ITIME must contain the month, in the range 1-12. + (2) + + ITIME must contain the day, in the range 1 to p, where + (3) p = 28, 29, 30 or 31, depending on the month and + year. + + ITIME must contain the hour, in the range 0-23. + (4) + + ITIME must contain the minute, in the range 0-59. + (5) + + ITIME must contain the second, in the range 0-59. + (6) + + ITIME must contain the millisecond, in the range 0- + (7) 999. + + 6. Error Indicators and Warnings + + None. + + 7. Accuracy + + The day name included as part of the character string returned by + this routine is calculated assuming that the date is part of the + Gregorian calendar. This calendar has been in operation in Europe + since October the 15th 1582, and in Great Britain since September + the 14th 1752. Entry to this routine with a date earlier than + these will therefore not return a day name that is historically + accurate. + + 8. Further Comments + + Two dates stored in character string format, as returned by this + routine, may be compared by X05ACF. + + 9. Example + + This program initialises a time in ITIME, and converts it to + character format by a call to X05ABF. + + The example program is not reproduced here. The source code for + all example programs is distributed with the NAG Foundation + Library software and should be available on-line. +\end{verbatim} +\endscroll +\end{page} +\begin{page}{manpageXXx05acf}{NAG On-line Documentation: x05acf} +\beginscroll +\begin{verbatim} + + + + X05ACF(3NAG) Foundation Library (12/10/92) X05ACF(3NAG) + + + + X05 -- Date and Time Utilities X05ACF + X05ACF -- NAG Foundation Library Routine Document + + Note: Before using this routine, please read the Users' Note for + your implementation to check implementation-dependent details. + The symbol (*) after a NAG routine name denotes a routine that is + not included in the Foundation Library. + + 1. Purpose + + X05ACF compares two date/time character strings, each stored in + the format returned by X05ABF. + + 2. Specification + + INTEGER FUNCTION X05ACF (CTIME1, CTIME2) + CHARACTER*(*) CTIME1, CTIME2 + + 3. Description + + X05ACF compares two date/time character strings, and returns an + integer that specifies which one is the earliest. The result is + an integer returned through the routine name, with meaning as + follows: + + X05ACF = -1: the first date/time string is earlier than the + second. + + X05ACF = 0: the two date/time strings are equivalent. + + X05ACF = 1: the first date/time string is later than the + second. + + 4. References + + None. + + 5. Parameters + + 1: CTIME1 -- CHARACTER*(*) Input + + 2: CTIME2 -- CHARACTER*(*) Input + On entry: the date/time strings to be compared. These are + expected be in the format returned by X05ABF, although + X05ACF will still attempt to interpret the strings if they + vary slightly from this format. See Section 8 for further + details. + + 6. Error Indicators and Warnings + + None. + + 7. Accuracy + + Not applicable. + + 8. Further Comments + + For flexibility, X05ACF will accept various formats for the two + date/time strings CTIME1 and CTIME2. + + The strings do not have to be the same length. It is permissible, + for example, to enter with one or both of the strings truncated + to a smaller length, in which case missing fields are treated as + zero. + + Each character string may be of any length, but everything after + character 80 is ignored. + + Each string may or may not include an alphabetic day name, such + as 'Wednesday', at its start. These day names are ignored, and no + check is made that the day name corresponds correctly to the rest + of the date. + + The month name may contain any number of characters provided it + uniquely identifies the month, however all characters that are + supplied are significant. + + Each field in the character string must be separated by one or + more spaces. + + The case of all alphabetic characters is insignificant. + + Any field in a date time string that is indecipherable according + to the above rules will be converted to a zero value internally. + Thus two strings that are completely indecipherable will compare + equal. + + According to these rules, all the following date/time strings are + equivalent: + + 'Thursday 10th July 1958 12:43:17.320' + + 'THU 10th JULY 1958 12:43:17.320' + + '10th Jul 1958 12:43:17.320' + + 9. Example + + This program initialises two date/time strings, and compares them + by a call to X05ACF. + + + The example program is not reproduced here. The source code for + all example programs is distributed with the NAG Foundation + Library software and should be available on-line. + +\end{verbatim} +\endscroll +\end{page} +\begin{page}{manpageXXx05baf}{NAG On-line Documentation: x05baf} +\beginscroll +\begin{verbatim} + + + + X05BAF(3NAG) Foundation Library (12/10/92) X05BAF(3NAG) + + + + X05 -- Date and Time Utilities X05BAF + X05BAF -- NAG Foundation Library Routine Document + + Note: Before using this routine, please read the Users' Note for + your implementation to check implementation-dependent details. + The symbol (*) after a NAG routine name denotes a routine that is + not included in the Foundation Library. + + 1. Purpose + + X05BAF returns the amount of processor time used since an + unspecified previous time, via the routine name. + + 2. Specification + + DOUBLE PRECISION FUNCTION X05BAF () + + 3. Description + + X05BAF returns the number of seconds of processor time used since + some previous time. The previous time is system dependent, but + may be, for example, the time the current job or the current + program started running. + + If the system clock of the host machine is inaccessible for any + reason, X05BAF returns the value zero. + + 4. References + + None. + + 5. Parameters + + None. + + 6. Error Indicators and Warnings + + None. + + 7. Accuracy + + The accuracy of the value returned depends on the accuracy of the + system clock on the host machine. + + 8. Further Comments + + Since the value returned by X05BAF is the amount of processor + time since some unspecified earlier time, no significance should + be placed on the value other than as a marker to be compared with + some later figure returned by X05BAF. The amount of processor + time that has elapsed between two calls of X05BAF can be simply + calculated as the earlier value subtracted from the later value. + + 9. Example + + This program makes a call to X05BAF, performs some computations, + makes another call to X05BAF, and gives the time used by the + computations as the difference between the two returned values. + + The example program is not reproduced here. The source code for + all example programs is distributed with the NAG Foundation + Library software and should be available on-line. +\end{verbatim} +\endscroll +\end{page} -- cgit v1.2.3