G13AHF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13AHF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13AHF produces forecasts of a time series, given a time series model which has already been fitted to the time series using G13AEF or G13AFF. The original observations are not required, since G13AHF uses as input either the original state set produced by G13AEF or G13AFF or the state set updated by a series of new observations using G13AGF. Standard errors of the forecasts are also provided.

2 Specification

SUBROUTINE G13AHF ( ST, NST, MR, PAR, NPAR, C, RMS, NFV, FVA, FSD, WA, NWA, IFAIL)
INTEGER | NST, MR(7), NPAR, NFV, NWA, IFAIL
REAL (KIND=nag_wp) | ST(NST), PAR(NPAR), C, RMS, FVA(NFV), FSD(NFV), WA(NWA)

3 Description

The original time series is xt, for t=1,2,…,n and parameters have been fitted to the model of this time series using G13AEF or G13AFF.
Forecasts of xt, for t=n+1,…,n+L, are calculated in five stages, as follows:
(i) | set at=0 for t=N+1,N+2,…,N+L, where N=n-d-D×s is the number of differenced values in the series;
(ii) | calculate the values of et, for t=N+1,…,N+L, and et=ϕ 1×e t-1+⋯+ ϕp×e t-p+at-θ 1×a t-1-⋯-θq×a t-q;
(iii) | calculate the values of wt, for t=N+1,…,N+L, where wt=Φ 1×w t-s+⋯+ ΦP×w t-s×P+et-Θ 1×e t-s-⋯-ΘQ×e t-s×Q and wt for t≤N are the first s×P values in the state set, corrected for the constant;
(iv) | add the constant term c to give the differenced series ∇d∇sD xt=wt+c, for t=N+1,…,N+L;
(v) | the differencing operations are reversed to reconstitute xt, for t=n+1,…,n+L.
The standard errors of these forecasts are given by st = V× ψ 02 + ψ 12 +…+ ψ t-n-1 2 1/2 , for t=n+1,…,n+L, where ψ 0=1, V is the residual variance of at, and ψj is the coefficient expressing the dependence of xt on a t-j.
To calculate ψj, for j=1,2,…,L-1, the following device is used.
A copy of the state set is initialized to zero throughout and the calculations outlined above for the construction of forecasts are carried out with the settings a N+1=1, and at=0, for t=N+2,…,N+L.
The resulting quantities corresponding to the sequence x N+1,x N+2,…,x N+L are precisely 1, ψ 1,ψ 2,…,ψ L-1.
The supplied time series model is used throughout these calculations, with the exception that the constant term c is taken to be zero.

4 References

None.

5 Arguments

1:   ST NST – REAL (KIND=nag_wp) arrayInput
On entry: the state set derived from G13AEF or G13AFF originally, or as modified using earlier calls of G13AGF.
2:   NST – INTEGERInput
On entry: the number of values in the state set array ST.
Constraint: NST=P×s+D×s+d+q+max p,Q×s. (As returned by G13AEF or G13AFF).
3:   MR 7 – INTEGER arrayInput
On entry: the orders vector p,d,q,P,D,Q,s of the ARIMA model, in the usual notation.
Constraints:
  • p,d,q,P,D,Q,s≥0;
  • p+q+P+Q>0;
  • s≠1;
  • if s=0, P+D+Q=0;
  • if s>1, P+D+Q>0.
4:   PAR NPAR – REAL (KIND=nag_wp) arrayInput
On entry: the estimates of the p values of the ϕ parameters, the q values of the θ parameters, the P values of the Φ parameters and the Q values of the Θ parameters which specify the model and which were output originally by G13AEF or G13AFF.
5:   NPAR – INTEGERInput
On entry: the number of ϕ, θ, Φ and Θ parameters in the model.
Constraint: NPAR=p+q+P+Q.
6:   C – REAL (KIND=nag_wp)Input
On entry: c, the value of the model constant. This will have been output by G13AEF or G13AFF.
7:   RMS – REAL (KIND=nag_wp)Input
On entry: V, the residual variance associated with the model.
If G13AFF was used to estimate the model, RMS should be set to S/NDF, where S and NDF were output by G13AFF.
If G13AEF was used to estimate the model, RMS should be set to S/ICOUNT 5, where S and ICOUNT 5 were output by G13AEF.
Constraint: RMS≥0.0.
8:   NFV – INTEGERInput
On entry: L, the required number of forecasts.
Constraint: NFV>0.
9:   FVA NFV – REAL (KIND=nag_wp) arrayOutput
On exit: NFV forecast values relating to the original undifferenced series.
10:   FSD NFV – REAL (KIND=nag_wp) arrayOutput
On exit: the standard errors associated with each of the NFV forecast values in FVA.
11:   WA NWA – REAL (KIND=nag_wp) arrayWorkspace
12:   NWA – INTEGERInput
On entry: the dimension of the array WA as declared in the (sub)program from which G13AHF is called.
Constraint: NWA≥4×NPAR+3×NST.
13:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | NPAR≠p+q+P+Q,
or | the orders vector MR is invalid (check the constraints given in Section 5).
IFAIL=2
On entry, NST≠P×s+D×s+d+q+max Q×s,p.
IFAIL=3
On entry, NFV≤0.
IFAIL=4
On entry, NWA<4×NPAR+3×NST.
IFAIL=5
On entry, RMS<0.0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The computations are believed to be stable.

8 Parallelism and Performance

G13AHF is not threaded in any implementation.

9 Further Comments

The time taken by G13AHF is approximately proportional to NFV×NPAR.

10 Example

The following program is based on the data derived in the example used to illustrate G13AGF.
These consist of a set of orders indicating that there are two moving average parameters (one non-seasonal, and one seasonal with periodicity 12).
The model constant is zero.
The state set contains 26 values.
In addition the residual mean-square derived when the model was originally fitted is given.
Twelve forecasts and their associated errors are obtained.

10.1 Program Text

Program Text (g13ahfe.f90)

10.2 Program Data

Program Data (g13ahfe.d)

10.3 Program Results

Program Results (g13ahfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13AJF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13AJF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13AJF applies a fully specified seasonal ARIMA model to an observed time series, generates the state set for forecasting and (optionally) derives a specified number of forecasts together with their standard deviations.

2 Specification

SUBROUTINE G13AJF ( MR, PAR, NPAR, C, KFC, X, NX, RMS, ST, IST, NST, NFV, FVA, FSD, IFV, ISF, W, IW, IFAIL)
INTEGER | MR(7), NPAR, KFC, NX, IST, NST, NFV, IFV, ISF(4), IW, IFAIL
REAL (KIND=nag_wp) | PAR(NPAR), C, X(NX), RMS, ST(IST), FVA(IFV), FSD(IFV), W(IW)

3 Description

The time series x 1,x 2,…,xn supplied to the routine is assumed to follow a seasonal autoregressive integrated moving average (ARIMA) model with known parameters.
The model is defined by the following relations.
(a) | ∇d∇sD xt-c=wt where ∇d∇sD xt is the result of applying non-seasonal differencing of order d and seasonal differencing of seasonality s and order D to the series xt, and c is a constant.
(b) | wt=Φ 1w t-s+Φ 2w t-2×s+⋯+ΦPw t-P×s+et-Θ 1e t-s-Θ 2e t-2×s-⋯-ΘQe t-Q×s. This equation describes the seasonal structure with seasonal period s; in the absence of seasonality it reduces to wt=et.
(c) | et=ϕ 1e t-1+ϕ 2e t-2+⋯+ϕpe t-p+at-θ 1a t-1-θ 2a t-2-⋯-θqa t-q. This equation describes the non-seasonal structure.
Given the series, the constant c, and the model parameters Φ, Θ, ϕ, θ, the routine computes the following.
(a) The state set required for forecasting. This contains the minimum amount of information required for forecasting and comprises:
(i) | the differenced series wt, for N-s×P≤t≤N;
(ii) | the d+D×s values required to reconstitute the original series xt from the differenced series wt;
(iii) | the intermediate series et, for N-max p,Q×s<t≤N;
(iv) | the residual series at, for N-q<t≤N, where N=n-d+D×s.
(b) A set of L forecasts of xt and their estimated standard errors, st, for t=n+1,…,n+L (L may be zero).
The forecasts and estimated standard errors are generated from the state set, and are identical to those that would be produced from the same state set by G13AHF.
Use of G13AJF should be confined to situations in which the state set for forecasting is unknown. Forecasting from the series requires recalculation of the state set and this is relatively expensive.

4 References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day

5 Arguments

1:   MR 7 – INTEGER arrayInput
On entry: the orders vector p,d,q,P,D,Q,s of the ARIMA model, in the usual notation.
Constraints:
  • p,d,q,P,D,Q,s≥0;
  • p+q+P+Q>0;
  • s≠1;
  • if s=0, P+D+Q=0;
  • if s>1, P+D+Q>0;
  • d+s×P+D≤n;
  • p+d-q+s×P+D-Q≤n.
2:   PAR NPAR – REAL (KIND=nag_wp) arrayInput
On entry: the p values of the ϕ parameters, the q values of the θ parameters, the P values of the Φ parameters, and the Q values of the Θ parameters, in that order.
3:   NPAR – INTEGERInput
On entry: the exact number of ϕ, θ, Φ and Θ parameters.
Constraint: NPAR=p+q+P+Q.
4:   C – REAL (KIND=nag_wp)Input
On entry: c, the expected value of the differenced series (i.e., c is the constant correction). Where there is no constant term, C must be set to 0.0.
5:   KFC – INTEGERInput
On entry: must be set to 0 if C was not estimated, and 1 if C was estimated. This is irrespective of whether or not C=0.0. The only effect is that the residual degrees of freedom are one greater when KFC=0. Assuming the supplied time series to be the same as that to which the model was originally fitted, this ensures an unbiased estimate of the residual mean-square.
Constraint: KFC=0 or 1.
6:   X NX – REAL (KIND=nag_wp) arrayInput
On entry: the n values of the original undifferenced time series.
7:   NX – INTEGERInput
On entry: n, the length of the original undifferenced time series.
8:   RMS – REAL (KIND=nag_wp)Output
On exit: the residual variance (mean square) associated with the model.
9:   ST IST – REAL (KIND=nag_wp) arrayOutput
On exit: the NST values of the state set.
10:   IST – INTEGERInput
On entry: the dimension of the array ST as declared in the (sub)program from which G13AJF is called.
Constraint: IST≥P×s+d+D×s+q+max p,Q×s. The expression on the right-hand side of the inequality is returned in NST.
11:   NST – INTEGEROutput
On exit: the number of values in the state set array ST.
12:   NFV – INTEGERInput
On entry: the required number of forecasts. If NFV≤0, no forecasts will be computed.
13:   FVA IFV – REAL (KIND=nag_wp) arrayOutput
On exit: if NFV>0, FVA contains the NFV forecast values relating to the original undifferenced time series.
14:   FSD IFV – REAL (KIND=nag_wp) arrayOutput
On exit: if NFV>0, FSD contains the estimated standard errors of the NFV forecast values.
15:   IFV – INTEGERInput
On entry: the dimension of the arrays FVA and FSD as declared in the (sub)program from which G13AJF is called.
Constraint: IFV≥max 1,NFV.
16:   ISF 4 – INTEGER arrayOutput
On exit: contains validity indicators, one for each of the four possible parameter types in the model (autoregressive, moving average, seasonal autoregressive, seasonal moving average), in that order.
Each indicator has the interpretation:
-1 | On entry the set of parameter values of this type does not satisfy the stationarity or invertibility test conditions.
-0 | No parameter of this type is in the model.
-1 | Valid parameter values of this type have been supplied.
17:   W IW – REAL (KIND=nag_wp) arrayWorkspace
18:   IW – INTEGERInput
On entry: the dimension of the array W as declared in the (sub)program from which G13AJF is called.
Constraint: IW≥6×n+5×p+q+P+Q+Q′2+11×Q′+3×P′+7,
where Q′=Q×s+q and P′=P×s+p.
19:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | NPAR≠p+q+P+Q,
or | the orders vector MR is invalid (check the constraints in Section 5),
or | KFC≠0 or 1.
IFAIL=2
On entry, NX-d-D×s≤NPAR+KFC, i.e., the number of terms in the differenced series is not greater than the number of parameters in the model. The model is over-parameterised.
IFAIL=3
On entry, the workspace array W is too small.
IFAIL=4
On entry, the state set array ST is too small. It must be at least as large as the exit value of NST.
IFAIL=5
Unable to calculate te latest estimates of the backforecasts.
IFAIL=6
On entry, valid values were not supplied for all parameter types in the model. Inspect array ISF for further information on the parameter type(s) in error.
IFAIL=7
On entry, IFV<max 1,NFV.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The computations are believed to be stable.

8 Parallelism and Performance

G13AJF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13AJF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

The time taken by G13AJF is approximately proportional to n and the square of the number of backforecasts derived.

10 Example

The data is that used in the example program for G13AFF. Five forecast values and their standard errors, together with the state set, are computed and printed.

10.1 Program Text

Program Text (g13ajfe.f90)

10.2 Program Data

Program Data (g13ajfe.d)

10.3 Program Results

Program Results (g13ajfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13AMF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13AMF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13AMF performs exponential smoothing using either single exponential, double exponential or a Holt–Winters method.

2 Specification

SUBROUTINE G13AMF ( MODE, ITYPE, P, PARAM, N, Y, K, INIT, NF, FV, FSE, YHAT, RES, DV, AD, R, IFAIL)
INTEGER | MODE, ITYPE, P, N, K, NF, IFAIL
REAL (KIND=nag_wp) | PARAM(*), Y(N), INIT(*), FV(NF), FSE(NF), YHAT(N), RES(N), DV, AD, R(*)

3 Description

Exponential smoothing is a relatively simple method of short term forecasting for a time series. G13AMF provides five types of exponential smoothing; single exponential, Brown's double exponential, linear Holt (also called double exponential smoothing in some references), additive Holt–Winters and multiplicative Holt–Winters. The choice of smoothing method used depends on the characteristics of the time series. If the mean of the series is only slowly changing then single exponential smoothing may be suitable. If there is a trend in the time series, which itself may be slowly changing, then double exponential smoothing may be suitable. If there is a seasonal component to the time series, e.g., daily or monthly data, then one of the two Holt–Winters methods may be suitable.
For a time series yt, for t=1,2,…,n, the five smoothing functions are defined by the following:
  • Single Exponential Smoothing
    mt = α yt + 1-α m t-1 y^t+f = mt var y^t+f = var εt 1+ f-1 α 2
  • Brown Double Exponential Smoothing
    mt = α yt + 1-α m t-1 rt = α mt - m t-1 + 1-α r t-1 y^ t+f = mt + f-1 + 1 / α rt var y^ t+f = var εt 1+ ∑ i=1 f-1 2 α+ i-1 α 2 2
  • Linear Holt Smoothing
    mt = α yt + 1-α m t-1 + ϕ r t-1 rt = γ mt - m t-1 + 1-γ ϕ r t-1 y^ t+f = mt + ∑ i=1 f ϕi rt var y^ t+f = var εt 1+ ∑ i=1 f-1 α + α γ ϕ ϕi-1 ϕ-1 2
  • Additive Holt–Winters Smoothing
    mt = α yt - s t-p + 1-α m t-1 +ϕ r t-1 rt = γ mt - m t-1 + 1-γ ϕ r t-1 st = β yt - mt + 1-β s t-p y^ t+f = mt + ∑ i=1 f ϕi rt + s t-p var y^ t+f = var εt 1+ ∑ i=1 f-1 ψi 2 ψi = 0 if ​i≥f α + αγϕ ϕ i -1 ϕ-1 if ​ i mod p≠0 α + α γ ϕ ϕi -1 ϕ-1 +β 1-α otherwise
  • Multiplicative Holt–Winters Smoothing
    mt = α yt / s t-p + 1-α m t-1 +ϕ r t-1 rt = γ mt - m t-1 + 1-γ ϕ r t-1 st = β yt / mt + 1-β s t-p y^ t+f = mt + ∑ i=1 f ϕi rt × s t-p var y^ t+f = var εt ∑ i=0 ∞ ∑ j=0 p-1 ψ j+ip s t+f s t+f-j 2
    and ψ is defined as in the additive Holt–Winters smoothing,
where mt is the mean, rt is the trend and st is the seasonal component at time t with p being the seasonal order. The f-step ahead forecasts are given by y^t+f and their variances by var y^ t+f . The term var εt is estimated as the mean deviation.
The parameters, α, β and γ control the amount of smoothing. The nearer these parameters are to one, the greater the emphasis on the current data point. Generally these parameters take values in the range 0.1 to 0.3. The linear Holt and two Holt–Winters smoothers include an additional parameter, ϕ, which acts as a trend dampener. For 0.0<ϕ<1.0 the trend is dampened and for ϕ>1.0 the forecast function has an exponential trend, ϕ=0.0 removes the trend term from the forecast function and ϕ=1.0 does not dampen the trend.
For all methods, values for α, β, γ and ψ can be chosen by trying different values and then visually comparing the results by plotting the fitted values along side the original data. Alternatively, for single exponential smoothing a suitable value for α can be obtained by fitting an ARIMA 0,1,1 model (see G13BEF). For Brown's double exponential smoothing and linear Holt smoothing with no dampening, (i.e., ϕ=1.0), suitable values for α and γ can be obtained by fitting an ARIMA 0,2,2 model. Similarly, the linear Holt method, with ϕ≠1.0, can be expressed as an ARIMA 1,2,2 model and the additive Holt–Winters, with no dampening, (ϕ=1.0), can be expressed as a seasonal ARIMA model with order p of the form ARIMA 0,1,p+10,1,0. There is no similar procedure for obtaining parameter values for the multiplicative Holt–Winters method, or the additive Holt–Winters method with ϕ≠1.0. In these cases parameters could be selected by minimizing a measure of fit using one of the nonlinear optimization routines in Chapter E04.
In addition to values for α, β, γ and ψ, initial values, m 0, r 0 and s-j, for j=0,1,…,p-1, are required to start the smoothing process. You can either supply these or they can be calculated by G13AMF from the first k observations. For single exponential smoothing the mean of the observations is used to estimate m 0. For Brown double exponential smoothing and linear Holt smoothing, a simple linear regression is carried out with the series as the dependent variable and the sequence 1,2,…,k as the independent variable. The intercept is then used to estimate m 0 and the slope to estimate r 0. In the case of the additive Holt–Winters method, the same regression is carried out, but a separate intercept is used for each of the p seasonal groupings. The slope gives an estimate for r 0 and the mean of the p intercepts is used as the estimate of m 0. The seasonal parameters s-j, for j=0,1,…,p-1, are estimated as the p intercepts – m 0. A similar approach is adopted for the multiplicative Holt–Winter's method.
One step ahead forecasts, y^ t+1 are supplied along with the residuals computed as y t+1 - y^ t+1 . In addition, two measures of fit are provided. The mean absolute deviation,
1 n ∑ t=1 n yt - y^ t
and the square root of the mean deviation
1 n ∑ t=1 n yt - y^ t 2 .

4 References

Chatfield C (1980) The Analysis of Time Series Chapman and Hall

5 Arguments

1:   MODE – INTEGERInput
On entry: indicates if G13AMF is continuing from a previous call or, if not, how the initial values are computed.
MODE=0
Required values for m 0, r 0 and s-j, for j=0,1,…,p-1, are supplied in INIT.
MODE=1
G13AMF continues from a previous call using values that are supplied in R.
MODE=2
Required values for m 0, r 0 and s-j, for j=0,1,…,p-1, are estimated using the first k observations.
Constraint: MODE=0, 1 or 2.
2:   ITYPE – INTEGERInput
On entry: the smoothing function.
ITYPE=1
Single exponential.
ITYPE=2
Brown double exponential.
ITYPE=3
Linear Holt.
ITYPE=4
Additive Holt–Winters.
ITYPE=5
Multiplicative Holt–Winters.
Constraint: ITYPE=1, 2, 3, 4 or 5.
3:   P – INTEGERInput
On entry: if ITYPE=4 or 5, the seasonal order, p, otherwise P is not referenced.
Constraint: if ITYPE=4 or 5, P>1.
4:   PARAM* – REAL (KIND=nag_wp) arrayInput
Note: the dimension of the array PARAM must be at least 1 if ITYPE=1 or 2, 3 if ITYPE=3 and at least 4 if ITYPE=4 or 5.
On entry: the smoothing parameters.
If ITYPE=1 or 2, PARAM 1=α and any remaining elements of PARAM are not referenced.
If ITYPE=3, PARAM 1=α, PARAM 2=γ, PARAM 3=ϕ and any remaining elements of PARAM are not referenced.
If ITYPE=4 or 5, PARAM 1=α, PARAM 2=γ, PARAM 3=β and PARAM 4=ϕ.
Constraints:
  • if ITYPE=1, 0.0≤α≤1.0;
  • if ITYPE=2, 0.0<α≤1.0;
  • if ITYPE=3, 0.0≤α≤1.0 and 0.0≤γ≤1.0 and ϕ≥0.0;
  • if ITYPE=4 or 5, 0.0≤α≤1.0 and 0.0≤γ≤1.0 and 0.0≤β≤1.0 and ϕ≥0.0.
5:   N – INTEGERInput
On entry: the number of observations in the series.
Constraint: N≥0.
6:   Y N – REAL (KIND=nag_wp) arrayInput
On entry: the time series.
7:   K – INTEGERInput
On entry: if MODE=2, the number of observations used to initialize the smoothing.
If MODE≠2, K is not referenced.
Constraints:
  • if MODE=2 and ITYPE=4 or 5, 2×P≤K≤N;
  • if MODE=2 and ITYPE=1, 2 or 3, 1≤K≤N.
8:   INIT* – REAL (KIND=nag_wp) arrayInput/Output
Note: the dimension of the array INIT must be at least 1 if ITYPE=1, 2 if ITYPE=2 or 3 and at least 2+P if ITYPE=4 or 5.
On entry: if MODE=0, the initial values for m 0, r 0 and s-j, for j=0,1,…,p-1, used to initialize the smoothing.
If ITYPE=1, INIT 1=m 0 and the remaining elements of INIT are not referenced.
If ITYPE=2 or 3, INIT 1=m 0 and INIT 2=r 0 and the remaining elements of INIT are not referenced.
If ITYPE=4 or 5, INIT 1=m 0, INIT 2=r 0 and INIT 3 to INIT p+2 hold the values for s-j, for j=0,1,…,p-1. The remaining elements of INIT are not referenced.
On exit: if MODE≠1, the values used to initialize the smoothing. These are in the same order as described above.
9:   NF – INTEGERInput
On entry: the number of forecasts required beyond the end of the series. Note, the one step ahead forecast is always produced.
Constraint: NF≥0.
10:   FV NF – REAL (KIND=nag_wp) arrayOutput
On exit: y^t+f, for f=1,2,…,NF, the next NF step forecasts. Where t=N, if MODE≠1, else t is the total number of smoothed and forecast values already produced.
11:   FSE NF – REAL (KIND=nag_wp) arrayOutput
On exit: the forecast standard errors for the values given in FV.
12:   YHAT N – REAL (KIND=nag_wp) arrayOutput
On exit: y^t+1, for t=1,2,…,N, the one step ahead forecast values, with YHAT i being the one step ahead forecast of Y i-1.
13:   RES N – REAL (KIND=nag_wp) arrayOutput
On exit: the residuals, y t+1 - y^ t+1 , for t=1,2,…,N.
14:   DV – REAL (KIND=nag_wp)Output
On exit: the square root of the mean deviation.
15:   AD – REAL (KIND=nag_wp)Output
On exit: the mean absolute deviation.
16:   R* – REAL (KIND=nag_wp) arrayInput/Output
Note: the dimension of the array R must be at least 13 if ITYPE=1, 2 or 3 and at least 13+P if ITYPE=4 or 5.
On entry: if MODE=1, R must contain the values as returned by a previous call to G05PMF or G13AMF, R need not be set otherwise.
If ITYPE=1, 2 or 3, only the first 13 elements of R are referenced, otherwise the first 13+p elements are referenced.
On exit: the information on the current state of the smoothing.
Constraint: if MODE=1, R must have been initialized by at least one previous call to G05PMF or G13AMF with MODE≠1, and R should not have been changed since the last call to G05PMF or G13AMF.
17:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, MODE=value.
Constraint: MODE=0, 1 or 2.
IFAIL=2
On entry, ITYPE=value.
Constraint: ITYPE=1, 2, 3, 4 or 5.
IFAIL=3
On entry, P=value.
Constraint: if ITYPE=4 or 5, P>1.
IFAIL=4
On entry, PARAM value=value.
Constraint: 0.0≤PARAM value≤1.0.
On entry, PARAM value=value.
Constraint: if ITYPE=2, 0.0<PARAM value≤1.0.
On entry, PARAM value=value.
Constraint: PARAM value≥0.0.
IFAIL=5
On entry, N=value.
Constraint: N≥0.
IFAIL=6
A multiplicative Holt–Winters model cannot be used with the supplied data.
IFAIL=7
On entry, K=value, 2×P=value.
Constraint: if MODE=2 and ITYPE=4 or 5, 2×P≤K.
On entry, K=value and N=value.
Constraint: if MODE=2 and ITYPE=4 or 5, 1≤K≤N.
IFAIL=9
On entry, NF=value.
Constraint: NF≥0.
IFAIL=16
On entry, the array R has not been initialized correctly.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

G13AMF is not threaded in any implementation.

9 Further Comments

Single exponential, Brown's double exponential and linear Holt smoothing methods are stable, whereas the two Holt–Winters methods can be affected by poor initial values for the seasonal components.
See also the routine document for G05PMF.

10 Example

This example smooths a time series relating to the rate of the earth's rotation about its polar axis.

10.1 Program Text

Program Text (g13amfe.f90)

10.2 Program Data

Program Data (g13amfe.d)

10.3 Program Results

Program Results (g13amfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13ASF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13ASF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
▸▿ 9 Further Comments
9.1 Timing
9.2 Choice of m
9.3 Approximate Standard Errors
9.4 Alternative Applications
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13ASF is a diagnostic checking routine suitable for use after fitting a Box–Jenkins ARMA model to a univariate time series using G13AEF or G13AFF. The residual autocorrelation function is returned along with an estimate of its asymptotic standard errors and correlations. Also, G13ASF calculates the Box–Ljung portmanteau statistic and its significance level for testing model adequacy.

2 Specification

SUBROUTINE G13ASF ( N, V, MR, M, PAR, NPAR, ISHOW, R, RCM, LDRCM, CHI, IDF, SIGLEV, IW, LIW, WORK, LWORK, IFAIL)
INTEGER | N, MR(7), M, NPAR, ISHOW, LDRCM, IDF, IW(LIW), LIW, LWORK, IFAIL
REAL (KIND=nag_wp) | V(N), PAR(NPAR), R(M), RCM(LDRCM,M), CHI, SIGLEV, WORK(LWORK)

3 Description

Consider the univariate multiplicative autoregressive-moving average model
ϕ B Φ BsWt-μ=θ B Θ Bs εt (1)
where Wt, for t=1,2,…,n, denotes a time series and εt, for t=1,2,…,n, is a residual series assumed to be normally distributed with zero mean and variance σ 2 (>0). The εt's are also assumed to be uncorrelated. Here μ is the overall mean term, s is the seasonal period and B is the backward shift operator such that Br Wt=W t-r. The polynomials in (1) are defined as follows:
ϕ B=1-ϕ 1 B-ϕ 2 B 2-⋯-ϕp Bp
is the non-seasonal autoregressive (AR) operator;
θ B= 1-θ 1 B-θ 2 B 2-⋯-θq Bq
is the non-seasonal moving average (MA) operator;
Φ Bs=1-Φ 1 Bs-Φ 2 B 2 s-⋯-ΦP B Ps
is the seasonal AR operator; and
Θ Bs= 1-Θ 1 Bs-Θ 2 B 2 s-⋯-ΘQ B Qs
is the seasonal MA operator. The model (1) is assumed to be stationary, that is the zeros of ϕ B and Φ Bs are assumed to lie outside the unit circle. The model (1) is also assumed to be invertible, that is the zeros of θ B and Θ Bs are assumed to lie outside the unit circle. When both Φ Bs and Θ Bs are absent from the model, that is when P=Q=0, then the model is said to be non-seasonal.
The estimated residual autocorrelation coefficient at lag l, r^l, is computed as:
r^l=∑t=l+1 n ε^t-l-ε-ε^t-ε- ∑t=1 n ε^t-ε- 2 ,  l=1,2,…
where ε^t denotes an estimate of the tth residual, εt, and ε-=∑t=1 n ε^t/n. A portmanteau statistic, Q m, is calculated from the formula (see Box and Ljung (1978)):
Q m=n n+2∑l=1 m r^l 2/n-l
where m denotes the number of residual autocorrelations computed. (Advice on the choice of m is given in Section 9.2.) Under the hypothesis of model adequacy, Q m has an asymptotic χ 2-distribution on m-p-q-P-Q degrees of freedom. Let r^T=r^1,r^2,…,r^m then the variance-covariance matrix of r^ is given by:
Var r^=Im-X XT X-1XT/n.
The construction of the matrix X is discussed in McLeod (1978). (Note that the mean, μ, and the residual variance, σ 2, play no part in calculating Var r^ and therefore are not required as input to G13ASF.)
Note: for additive models with fixed parameter values (i.e., fitted by G13DDF) G13DSF should be used instead of G13ASF.

4 References

Box G E P and Ljung G M (1978) On a measure of lack of fit in time series models Biometrika 65 297–303
McLeod A I (1978) On the distribution of the residual autocorrelations in Box–Jenkins models J. Roy. Statist. Soc. Ser. B 40 296–302

5 Arguments

1:   N – INTEGERInput
On entry: n, the number of observations in the residual series.
If G13ASF is used following a call to G13AEF, then N must be the value ICOUNT 2 returned by G13AEF.
If G13ASF is used following a call to G13AFF, then N must be the value NRES returned by G13AFF.
Constraint: N≥3.
2:   V N – REAL (KIND=nag_wp) arrayInput
On entry: V t must contain an estimate of εt, for t=1,2,…,n.
If G13ASF is used following a call to G13AEF then the actual argument V must be EXR ICOUNT 1+1 as returned by G13AEF.
If G13ASF is used following a call to G13AFF then the actual argument V must be RES as returned by G13AFF.
Constraint: V must contain at least two distinct elements.
3:   MR 7 – INTEGER arrayInput
On entry: the orders vector (p, d, q, P, D, Q, s) as supplied to G13AEF or G13AFF.
Constraints:
  • p,q,P,Q,s≥0;
  • p+q+P+Q>0;
  • if s=0, then P=0 and Q=0.
4:   M – INTEGERInput
On entry: the value of m, the number of residual autocorrelations to be computed. See Section 9.2 for advice on the value of M.
Constraint: NPAR<M<N.
5:   PAR NPAR – REAL (KIND=nag_wp) arrayInput
On entry: the parameter estimates in the order ϕ 1,ϕ 2,…,ϕp, θ 1,θ 2,…,θq, Φ 1,Φ 2,…,ΦP, Θ 1,Θ 2,…,ΘQ only.
Constraint: the elements in PAR must satisfy the stationarity and invertibility conditions.
6:   NPAR – INTEGERInput
On entry: the total number of ϕ, θ, Φ and Θ parameters, i.e., NPAR=p+q+P+Q.
Constraint: NPAR=MR 1+MR 3+MR 4+MR 6.
7:   ISHOW – INTEGERInput
On entry: must be nonzero if the residual autocorrelations, their standard errors and the portmanteau statistics are to be printed and zero otherwise.
These quantities are available also as output variables in R, RCM, CHI, IDF and SIGLEV.
8:   R M – REAL (KIND=nag_wp) arrayOutput
On exit: an estimate of the residual autocorrelation coefficient at lag l, for l=1,2,…,m. If IFAIL=3 on exit then all elements of R are set to zero.
9:   RCM LDRCMM – REAL (KIND=nag_wp) arrayOutput
On exit: the estimated standard errors and correlations of the elements in the array R. The correlation between R i and R j is returned as RCM ij except that if i=j then RCM ij contains the standard error of R i. If on exit, IFAIL≥5, then all off-diagonal elements of RCM are set to zero and all diagonal elements are set to 1/n.
10:   LDRCM – INTEGERInput
On entry: the first dimension of the array RCM as declared in the (sub)program from which G13ASF is called.
Constraint: LDRCM≥M.
11:   CHI – REAL (KIND=nag_wp)Output
On exit: the value of the portmanteau statistic, Q m. If IFAIL=3 on exit then CHI is returned as zero.
12:   IDF – INTEGEROutput
On exit: the number of degrees of freedom of CHI.
13:   SIGLEV – REAL (KIND=nag_wp)Output
On exit: the significance level of CHI based on IDF degrees of freedom. If IFAIL=3 on exit, SIGLEV is returned as one.
14:   IW LIW – INTEGER arrayWorkspace
15:   LIW – INTEGERInput
On entry: the dimension of the array IW as declared in the (sub)program from which G13ASF is called.
Constraint: LIW≥max MR 1,MR 3,MR 4,MR 6.
16:   WORK LWORK – REAL (KIND=nag_wp) arrayWorkspace
17:   LWORK – INTEGERInput
On entry: the dimension of the array WORK as declared in the (sub)program from which G13ASF is called.
Constraint: LWORK≥NPAR×M+NPAR+1+max MR 1,MR 3,MR 4,MR 6× max MR 7,1+M.
18:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if IFAIL≠0 on exit, the recommended value is -1. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Note: G13ASF may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the routine:
IFAIL=1
On entry, | MR 1<0,
or | MR 3<0,
or | MR 4<0,
or | MR 6<0,
or | MR 7<0,
or | MR 7=0 and either MR 4>0 or MR 6>0,
or | MR 1=MR 3=MR 4=MR 6=0,
or | M≤NPAR,
or | M≥N,
or | N<3,
or | NPAR≠MR 1+MR 3+MR 4+MR 6,
or | LDRCM<M,
or | LIW is too small,
or | LWORK is too small.
IFAIL=2
On entry, the autoregressive (or moving average) parameters are extremely close to or outside the stationarity (or invertibility) region. To proceed, you must supply different parameter estimates in the array PAR.
IFAIL=3
On entry, the residuals are practically identical giving zero (or near zero) variance. In this case CHI is set to zero and SIGLEV to one and all the elements of R are set to zero.
IFAIL=4
This is an unlikely exit brought about by an excessive number of iterations being needed to evaluate the zeros of the AR or MA polynomials. All output arguments are undefined.
IFAIL=5
On entry, one or more of the AR operators has a factor in common with one or more of the MA operators. To proceed, this common factor must be deleted from the model. In this case, the off-diagonal elements of RCM are returned as zero and the diagonal elements set to 1/n. All other output quantities will be correct.
IFAIL=6
This is an unlikely exit. At least one of the diagonal elements of RCM was found to be either negative or zero. In this case all off-diagonal elements of RCM are returned as zero and all diagonal elements of RCM set to 1/n.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The computations are believed to be stable.

8 Parallelism and Performance

G13ASF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13ASF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

9.1 Timing

The time taken by G13ASF depends upon the number of residual autocorrelations to be computed, m.

9.2 Choice of m

The number of residual autocorrelations to be computed, m should be chosen to ensure that when the ARMA model (1) is written as either an infinite order autoregressive process:
Wt-μ=∑j=1∞πj W t-j-μ+εt
or as an infinite order moving average process:
Wt-μ=∑j= 1∞ψjε t-j+εt
then the two sequences π 1,π 2,… and ψ 1,ψ 2,… are such that πj and ψj are approximately zero for j>m. An overestimate of m is therefore preferable to an under-estimate of m. In many instances the choice m=10 will suffice. In practice, to be on the safe side, you should try setting m=20.

9.3 Approximate Standard Errors

When IFAIL=5 or 6 all the standard errors in RCM are set to 1/n. This is the asymptotic standard error of r^l when all the autoregressive and moving average parameters are assumed to be known rather than estimated.

9.4 Alternative Applications

G13ASF may be used for diagnostic checking of suitable univariate ARMA models, as described in Section 3, fitted by G13BEF or G13DDF. Great care must be taken in obtaining the input values for G13ASF from the output values from G13BEF or G13DDF.

10 Example

This example fits an ARIMA1,1,2 model to a series of 30 observations. 10 residual autocorrelations are computed.

10.1 Program Text

Program Text (g13asfe.f90)

10.2 Program Data

Program Data (g13asfe.d)

10.3 Program Results

Program Results (g13asfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13AUF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13AUF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13AUF calculates the range (or standard deviation) and the mean for groups of successive time series values. It is intended for use in the construction of range-mean plots.

2 Specification

SUBROUTINE G13AUF ( N, Z, M, NGRPS, RS, Y, MEAN, IFAIL)
INTEGER | N, M, NGRPS, IFAIL
REAL (KIND=nag_wp) | Z(N), Y(NGRPS), MEAN(NGRPS)
CHARACTER(1) | RS

3 Description

Let Z 1,Z 2,…,Zn denote n successive observations in a time series. The series may be divided into groups of m successive values and for each group the range or standard deviation (depending on a user-supplied option) and the mean are calculated. If n is not a multiple of m then groups of equal size m are found starting from the end of the series of observations provided, and any remaining observations at the start of the series are ignored. The number of groups used, k, is the integer part of n/m. If you wish to ensure that no observations are ignored then the number of observations, n, should be chosen so that n is divisible by m.
The mean, Mi, the range, Ri, and the standard deviation, Si, for the ith group are defined as
Mi=1 m∑j=1 m Z l+m i-1+j Ri=max 1≤j≤m Z l+m i-1+j-min 1≤j≤m Z l+m i-1+j
and
Si= 1 m- 1 ∑j= 1 m Z l+m i- 1+j-Mi 2
where l=n-km, the number of observations ignored.
For seasonal data it is recommended that m should be equal to the seasonal period. For non-seasonal data the recommended group size is 8.
A plot of range against mean or of standard deviation against mean is useful for finding a transformation of the series which makes the variance constant. If the plot appears random or the range (or standard deviation) seems to be constant irrespective of the mean level then this suggests that no transformation of the time series is called for. On the other hand an approximate linear relationship between range (or standard deviation) and mean would indicate that a log transformation is appropriate. Further details may be found in either Jenkins (1979) or McLeod (1982).
You have the choice of whether to use the range or the standard deviation as a measure of variability. If the group size is small they are both equally good but if the group size is fairly large (e.g., m=12 for monthly data) then the range may not be as good an estimate of variability as the standard deviation.

4 References

Jenkins G M (1979) Practical Experiences with Modelling and Forecasting Time Series GJP Publications, Lancaster
McLeod G (1982) Box–Jenkins in Practice. 1: Univariate Stochastic and Single Output Transfer Function/Noise Analysis GJP Publications, Lancaster

5 Arguments

1:   N – INTEGERInput
On entry: n, the number of observations in the time series.
Constraint: N≥M.
2:   Z N – REAL (KIND=nag_wp) arrayInput
On entry: Z t must contain the tth observation Zt, for t=1,2,…,n.
3:   M – INTEGERInput
On entry: m, the group size.
Constraint: M≥2.
4:   NGRPS – INTEGERInput
On entry: k, the number of groups.
Constraint: NGRPS=int N/M.
5:   RS – CHARACTER(1)Input
On entry: indicates whether ranges or standard deviations are to be calculated.
RS='R'
Ranges are calculated.
RS='S'
Standard deviations are calculated.
Constraint: RS='R' or 'S'.
6:   Y NGRPS – REAL (KIND=nag_wp) arrayOutput
On exit: Y i contains the range or standard deviation, as determined by RS, of the ith group of observations, for i=1,2,…,k.
7:   MEAN NGRPS – REAL (KIND=nag_wp) arrayOutput
On exit: MEAN i contains the mean of the ith group of observations, for i=1,2,…,k.
8:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | N<M,
or | M<2,
or | NGRPS≠ integer part of N/M.
IFAIL=2
On entry, RS is not equal to 'R' or 'S'.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The computations are believed to be stable.

8 Parallelism and Performance

G13AUF is not threaded in any implementation.

9 Further Comments

The time taken by G13AUF is approximately proportional to n.

10 Example

The following program produces the statistics for a range-mean plot for a series of 100 observations divided into groups of 8.

10.1 Program Text

Program Text (g13aufe.f90)

10.2 Program Data

Program Data (g13aufe.d)

10.3 Program Results

Program Results (g13aufe.r)

GnuplotProduced by GNUPLOT 4.6 patchlevel 3 20 40 60 80 100 120 140 160 0 10 20 30 40 50 60 70 80 Range Mean Example Program Plot of Range vs Mean (Y vs Mean) gnuplot_plot_1
G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13AWF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13AWF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13AWF returns the (augmented) Dickey–Fuller unit root test.

2 Specification

FUNCTION G13AWF ( TYPE, P, N, Y, IFAIL)
REAL (KIND=nag_wp) G13AWF
INTEGER | TYPE, P, N, IFAIL
REAL (KIND=nag_wp) | Y(N)

3 Description

If the root of the characteristic equation for a time series is one then that series is said to have a unit root. Such series are nonstationary. G13AWF returns one of three types of (augmented) Dickey–Fuller test statistic: τ, τμ or ττ, used to test for a unit root, a unit root with drift or a unit root with drift and a deterministic time trend, respectively.
To test whether a time series, yt, for t=1,2,…,n, has a unit root, the regression model
∇yt = β 1 y t-1 + ∑ i=1 p-1 δi ∇ y t-i +εt
is fitted and the test statistic τ constructed as
τ = β^1 σ 11
where ∇ is the difference operator, with ∇yt = yt- y t-1 , and where β^1 and σ 11 are the least squares estimate and associated standard error for β 1 respectively.
To test for a unit root with drift the regression model
∇yt = β 1 y t-1 + ∑ i=1 p-1 δi ∇ y t-i +α +εt
is fit and the test statistic τμ constructed as
τμ = β^1 σ 11
To test for a unit root with drift and deterministic time trend the regression model
∇yt = β 1 y t-1 + ∑ i=1 p-1 δi ∇ y t-i +α +β 2 t +εt
is fit and the test statistic ττ constructed as
ττ = β^1 σ 11
The distributions of the three test statistics; τ, τμ and ττ, are nonstandard. An associated probability can be obtained from G01EWF.

4 References

Dickey A D (1976) Estimation and hypothesis testing in nonstationary time series PhD Thesis Iowa State University, Ames, Iowa
Dickey A D and Fuller W A (1979) Distribution of the estimators for autoregressive time series with a unit root J. Am. Stat. Assoc. 74 366 427–431

5 Arguments

1:   TYPE – INTEGERInput
On entry: the type of unit test for which the probability is required.
TYPE=1
A unit root test will be performed and τ returned.
TYPE=2
A unit root test with drift will be performed and τμ returned.
TYPE=3
A unit root test with drift and deterministic time trend will be performed and ττ returned.
Constraint: TYPE=1, 2 or 3.
2:   P – INTEGERInput
On entry: p, the degree of the autoregressive (AR) component of the Dickey–Fuller test statistic. When p>1 the test is usually referred to as the augmented Dickey–Fuller test.
Constraint: P>0.
3:   N – INTEGERInput
On entry: n, the length of the time series.
Constraints:
  • if TYPE=1, N>2⁢P;
  • if TYPE=2, N>2⁢P+1;
  • if TYPE=3, N>2⁢P+2.
4:   Y N – REAL (KIND=nag_wp) arrayInput
On entry: y, the time series.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=11
On entry, TYPE=value.
Constraint: TYPE=1, 2 or 3.
IFAIL=21
On entry, P=value.
Constraint: P>0.
IFAIL=31
On entry, N=value.
Constraint: N>value.
IFAIL=41
On entry, the design matrix used in the estimation of β 1 is not of full rank, this is usually due to all elements of the series being virtually identical. The returned statistic is therefore not unique and likely to be meaningless.
IFAIL=42
σ 11=0, therefore depending on the sign of β^1, a large positive or negative value has been returned.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

None.

8 Parallelism and Performance

G13AWF is not threaded in any implementation.

9 Further Comments

None.

10 Example

In this example a Dickey–Fuller unit root test is applied to a time series related to the rate of the earth's rotation about its polar axis.

10.1 Program Text

Program Text (g13awfe.f90)

10.2 Program Data

Program Data (g13awfe.d)

10.3 Program Results

Program Results (g13awfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13BAF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13BAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13BAF filters a time series by an ARIMA model.

2 Specification

SUBROUTINE G13BAF ( Y, NY, MR, NMR, PAR, NPAR, CY, WA, NWA, B, NB, IFAIL)
INTEGER | NY, MR(NMR), NMR, NPAR, NWA, NB, IFAIL
REAL (KIND=nag_wp) | Y(NY), PAR(NPAR), CY, WA(NWA), B(NB)

3 Description

From a given series y 1,y 2,…,yn, a new series b 1,b 2,…,bn is calculated using a supplied (filtering) ARIMA model. This model will be one which has previously been fitted to a series xt with residuals at. The equations defining bt in terms of yt are very similar to those by which at is obtained from xt. The only dissimilarity is that no constant correction is applied after differencing. This is because the series yt is generally distinct from the series xt with which the model is associated, though yt may be related to xt. Whilst it is appropriate to apply the ARIMA model to yt so as to preserve the same relationship between bt and at as exists between yt and xt, the constant term in the ARIMA model is inappropriate for yt. The consequence is that bt will not necessarily have zero mean.
The equations are precisely:
wt=∇d∇sD yt, (1)
the appropriate differencing of yt; both the seasonal and non-seasonal inverted autoregressive operations are then applied,
ut=wt-Φ 1w t-s-⋯-ΦPw t-s×P (2)
vt=ut-ϕ 1u t-1-⋯-ϕpu t-p (3)
followed by the inverted moving average operations
zt=vt+Θ 1z t-s+⋯+ΘQz t-s×Q (4)
bt=zt+θ 1b t-1+⋯+θqb t-q. (5)
Because the filtered series value bt depends on present and past values yt,y t-1,…, there is a problem arising from ignorance of y 0,y-1,… which particularly affects calculation of the early values b 1,b 2,…, causing ‘transient errors’. The routine allows two possibilities.
(i) | The equations (1), (2) and (3) are applied from successively later time points so that all terms on their right-hand sides are known, with vt being defined for t=1+d+s×D+s×P,…,n. Equations (4) and (5) are then applied over the same range, taking any values on the right-hand side associated with previous time points to be zero. This procedure may still however result in unacceptably large transient errors in early values of bt.
(ii) | The unknown values y 0,y-1,… are estimated by backforecasting. This requires that an ARIMA model distinct from that which has been supplied for filtering, should have been previously fitted to yt.
For efficiency, you are asked to supply both this ARIMA model for yt and a limited number of backforecasts which are prefixed to the known values of yt. Within the routine further backforecasts of yt, and the series wt, ut, vt in (1), (2) and (3) are then easily calculated, and a set of linear equations solved for backforecasts of zt,bt for use in (4) and (5) in the case that q+Q>0.
Even if the best model for yt is not available, a very approximate guess such as
yt=c+et
or
∇ yt=et
can help to reduce the transients substantially.
The backforecasts which need to be prefixed to yt are of length Qy′=qy+sy×Qy, where qy and Qy are the non-seasonal and seasonal moving average orders and sy the seasonal period for the ARIMA model of yt. Thus you need not carry out the backforecasting exercise if Qy′=0. Otherwise, the series y 1,y 2,…,yn should be reversed to obtain yn,y n-1,…,y 1 and G13AJF should be used to forecast Qy′ values, y^0,…,y^1-Qy′. The ARIMA model used is that fitted to yt (as a forward series) except that, if dy+Dy is odd, the constant should be changed in sign (to allow, for example, for the fact that a forward upward trend is a reversed downward trend). The ARIMA model for yt supplied to the filtering routine must however have the appropriate constant for the forward series.
The series y^1-Qy′,…,y^0,y 1,…,yn is then supplied to the routine, and a corresponding set of values returned for bt.

4 References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day

5 Arguments

1:   Y NY – REAL (KIND=nag_wp) arrayInput
On entry: the Qy′ backforecasts, starting with backforecast at time 1-Qy′ to backforecast at time 0, followed by the time series starting at time 1, where Qy′=MR 10+MR 13×MR 14. If there are no backforecasts, either because the ARIMA model for the time series is not known, or because it is known but has no moving average terms, then the time series starts at the beginning of Y.
2:   NY – INTEGERInput
On entry: the total number of backforecasts and time series data points in array Y.
Constraint: NY≥max 1+Qy′,NPAR.
3:   MR NMR – INTEGER arrayInput
On entry: the orders vector for the filtering model, followed by the orders vector for the ARIMA model for the time series if the latter is known. The orders appear in the standard sequence p,d,q,P,D,Q,s as given in the G13 Chapter Introduction. If the ARIMA model for the time series is supplied, then the routine will assume that the first Qy′ values of the array Y are backforecasts.
Constraints:
the filtering model is restricted in the following ways:
  • MR 1+MR 3+MR 4+MR 6>0, i.e., filtering by a model which contains only differencing terms is not permitted;
  • MR k≥0, for k=1,2,…,7;
  • if MR 7=0, MR 4+MR 5+MR 6=0;
  • if MR 7≠0, MR 4+MR 5+MR 6≠0;
  • MR 7≠1.
the ARIMA model for the time series is restricted in the following ways:
  • MR k≥0, for k=8,9,…,14;
  • if MR 14=0, MR 11+MR 12+MR 13=0;
  • if MR 14≠0, MR 11+MR 12+MR 13≠0;
  • MR 14≠1.
4:   NMR – INTEGERInput
On entry: the number of values specified in the array MR. It takes the value 7 if no ARIMA model for the time series is supplied but otherwise it takes the value 14. Thus NMR acts as an indicator as to whether backforecasting can be carried out.
Constraint: NMR=7 or 14.
5:   PAR NPAR – REAL (KIND=nag_wp) arrayInput
On entry: the parameters of the filtering model, followed by the parameters of the ARIMA model for the time series, if supplied. Within each model the parameters are in the standard order of non-seasonal AR and MA followed by seasonal AR and MA.
6:   NPAR – INTEGERInput
On entry: the total number of parameters held in array PAR.
Constraints:
  • if NMR=7, NPAR=MR 1+MR 3+MR 4+MR 6;
  • if NMR=14, NPAR=MR 1+MR 3+MR 4+MR 6+ MR 8+MR 10+MR 11+MR 13.
Note: the first constraint (i.e., MR 1+MR 3+MR 4+MR 6>0) on the orders of the filtering model, in argument MR, ensures that NPAR>0.
7:   CY – REAL (KIND=nag_wp)Input
On entry: if the ARIMA model is known (i.e., NMR=14), CY must specify the constant term of the ARIMA model for the time series. If this model is not known (i.e., NMR=7), then CY is not used.
8:   WA NWA – REAL (KIND=nag_wp) arrayWorkspace
9:   NWA – INTEGERInput
On entry: the dimension of the array WA as declared in the (sub)program from which G13BAF is called. Workspace is only required if the ARIMA model for the time series is known.
Constraints:
let K=MR 3+MR 6×MR 7+MR 8+MR 9+MR 11+MR 12×MR 14,
then
  • if NMR=14, NWA≥K×K+2;
  • if NMR=7, NWA≥1.
10:   B NB – REAL (KIND=nag_wp) arrayOutput
On exit: the filtered output series. If the ARIMA model for the time series was known, and hence Qy′ backforecasts were supplied in Y, then B contains Qy′ ‘filtered’ backforecasts followed by the filtered series. Otherwise, the filtered series begins at the start of B just as the original series began at the start of Y. In either case, if the value of the series at time t is held in Y t, then the filtered value at time t is held in B t.
11:   NB – INTEGERInput
On entry: the dimension of the array B as declared in the (sub)program from which G13BAF is called. In addition to holding the returned filtered series, B is also used as an intermediate work array if the ARIMA model for the time series was known.
Constraints:
  • if NMR=14, NB≥NY+max K 3,K 1+K 2;
  • if NMR=7, NB≥NY.
Where
  • K 1=MR 1+MR 4×MR 7;
  • K 2=MR 2+MR 5×MR 7;
  • K 3=MR 3+MR 6×MR 7.
12:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, NMR≠7 and NMR≠14.
IFAIL=2
On entry, the orders vector MR does not satisfy the constraints given in Section 5.
IFAIL=3
On entry, NPAR is inconsistent with the contents of MR (see Section 5).
IFAIL=4
On entry, NY is too small to successfully carry out the requested filtering, (see Section 5).
IFAIL=5
On entry, the work array WA is too small.
IFAIL=6
On entry, the array B is too small.
IFAIL=7
The orders vector for the filtering model is invalid.
IFAIL=8
The orders vector for the ARIMA model is invalid. (Only occurs if NMR=14.)
IFAIL=9
The initial values of the filtered series are indeterminate for the given models.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Accuracy and stability are high except when the MA parameters are close to the invertibility boundary.

8 Parallelism and Performance

G13BAF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13BAF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

If an ARIMA model is supplied, a local workspace array of fixed length is allocated internally by G13BAF. The total size of this array amounts to K integer elements, where K is the expression defined in the description of the argument WA.
The time taken by G13BAF is approximately proportional to
NY×MR 1+MR 3+MR 4+MR 6,
with an appreciable fixed increase if an ARIMA model is supplied for the time series.

10 Example

This example reads a time series of length 296. It reads the univariate ARIMA 4,0,2,0,0,0,0 model and the ARIMA filtering 3,0,0,0,0,0,0 model for the series. Two initial backforecasts are required and these are calculated by a call to G13AJF . The backforecasts are inserted at the start of the series and G13BAF is called to perform the calculations.

10.1 Program Text

Program Text (g13bafe.f90)

10.2 Program Data

Program Data (g13bafe.d)

10.3 Program Results

Program Results (g13bafe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13BBF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13BBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13BBF filters a time series by a transfer function model.

2 Specification

SUBROUTINE G13BBF ( Y, NY, MR, NMR, PAR, NPAR, CY, WA, IWA, B, NB, IFAIL)
INTEGER | NY, MR(NMR), NMR, NPAR, IWA, NB, IFAIL
REAL (KIND=nag_wp) | Y(NY), PAR(NPAR), CY, WA(IWA), B(NB)

3 Description

From a given series y 1,y 2,…,yn a new series b 1,b 2,…,bn is calculated using a supplied (filtering) transfer function model according to the equation
bt=δ 1b t-1+δ 2b t-2+⋯+δpb t-p+ω 0y t-b-ω 1y t-b-1-⋯-ωqy t-b-q. (1)
As in the use of G13BAF, large transient errors may arise in the early values of bt due to ignorance of yt for t<0, and two possibilities are allowed.
(i) | The equation (1) is applied from t=1+b+q,…,n so all terms in yt on the right-hand side of (1) are known, the unknown set of values bt for t=b+q,…,b+q+1-p being taken as zero.
(ii) | The unknown values of yt for t≤0 are estimated by backforecasting exactly as for G13BAF.

4 References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day

5 Arguments

1:   Y NY – REAL (KIND=nag_wp) arrayInput
On entry: the Qy′ backforecasts starting with backforecast at time 1-Qy′ to backforecast at time 0 followed by the time series starting at time 1, where Qy′=MR 6+MR 9×MR 10. If there are no backforecasts either because the ARIMA model for the time series is not known or because it is known but has no moving average terms, then the time series starts at the beginning of Y.
2:   NY – INTEGERInput
On entry: the total number of backforecasts and time series data points in array Y.
Constraint: NY≥max 1+Qy′,NPAR.
3:   MR NMR – INTEGER arrayInput
On entry: the orders vector for the filtering transfer function model followed by the orders vector for the ARIMA model for the time series if the latter is known. The transfer function model orders appear in the standard form b,q,p as given in the G13 Chapter Introduction. Note that if the ARIMA model for the time series is supplied then the routine will assume that the first Qy′ values of the array Y are backforecasts.
Constraints:
the filtering model is restricted in the following way:
  • MR 1, ​MR 2, ​MR 3≥0.
the ARIMA model for the time series is restricted in the following ways:
  • MR k≥0, for k=4,5,…,10;
  • if MR 10=0, MR 7+MR 8+MR 9=0;
  • if MR 10≠0, MR 7+MR 8+MR 9≠0;
  • MR 10≠1.
4:   NMR – INTEGERInput
On entry: the number of values supplied in the array MR. It takes the value 3 if no ARIMA model for the time series is supplied but otherwise it takes the value 10. Thus NMR acts as an indicator as to whether backforecasting can be carried out.
Constraint: NMR=3 or 10.
5:   PAR NPAR – REAL (KIND=nag_wp) arrayInput
On entry: the parameters of the filtering transfer function model followed by the parameters of the ARIMA model for the time series. In the transfer function model the parameters are in the standard order of MA-like followed by AR-like operator parameters. In the ARIMA model the parameters are in the standard order of non-seasonal AR and MA followed by seasonal AR and MA.
6:   NPAR – INTEGERInput
On entry: the total number of parameters held in array PAR.
Constraints:
  • if NMR=3, NPAR=MR 2+MR 3+1;
  • if NMR=10, NPAR=MR 2+MR 3+1+MR 4+MR 6+MR 7+MR 9.
7:   CY – REAL (KIND=nag_wp)Input
On entry: if the ARIMA model is known (i.e., NMR=10), CY must specify the constant term of the ARIMA model for the time series. If this model is not known (i.e., NMR=3) then CY is not used.
8:   WA IWA – REAL (KIND=nag_wp) arrayWorkspace
9:   IWA – INTEGERInput
On entry: the dimension of the array WA as declared in the (sub)program from which G13BBF is called.
Constraints:
let K=MR 3+MR 4+MR 5+MR 7+MR 8×MR 10,
then
  • if NMR=3, IWA≥MR 1+NPAR;
  • if NMR=10, IWA≥MR 1+NPAR+K×K+2.
10:   B NB – REAL (KIND=nag_wp) arrayOutput
On exit: the filtered output series. If the ARIMA model for the time series was known, and hence Qy′ backforecasts were supplied in Y, then B contains Qy′ ‘filtered’ backforecasts followed by the filtered series. Otherwise, the filtered series begins at the start of B just as the original series began at the start of Y. In either case, if the value of the series at time t is held in Y t, then the filtered value at time t is held in B t.
11:   NB – INTEGERInput
On entry: the dimension of the array B as declared in the (sub)program from which G13BBF is called.
In addition to holding the returned filtered series, B is also used as an intermediate work array if the ARIMA model for the time series is known.
Constraints:
  • if NMR=3, NB≥NY;
  • if NMR=10, NB≥NY+max MR 1+MR 2,MR 3.
12:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | NMR≠3 and NMR≠10,
or | MR i<0, for i=1,2,…,NMR,
or | NMR=10 and MR 10=1,
or | NMR=10 and MR 10=0 and MR 7+MR 8+MR 9≠0,
or | NMR=10 and MR 10≠0, and MR 7+MR 8+MR 9=0,
or | NPAR is inconsistent with the contents of MR,
or | WA is too small,
or | B is too small.
IFAIL=2
A supplied model has parameter values which have failed the validity test.
IFAIL=3
The supplied time series is too short to carry out the requested filtering successfully.
IFAIL=4
This only occurs when an ARIMA model for the time series has been supplied. The matrix which is used to solve for the starting values for MA filtering is singular.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Accuracy and stability are high except when the AR-like parameters are close to the invertibility boundary. All calculations are performed in basic precision except for one inner product type calculation which on machines of low precision is performed in additional precision.

8 Parallelism and Performance

G13BBF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13BBF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

If an ARIMA model is supplied, a local workspace array of fixed length is allocated internally by G13BBF. The total size of this array amounts to K integer elements, where K is the expression defined in the description of the argument WA.
The time taken by G13BBF is roughly proportional to the product of the length of the series and number of parameters in the filtering model with appreciable increase if an ARIMA model is supplied for the time series.

10 Example

This example reads a time series of length 296. It reads one univariate ARIMA 1,1,0,0,1,1,12 model for the series and the 0,13,12 filtering transfer function model. 12 initial backforecasts are required and these are calculated by a call to G13AJF . The backforecasts are inserted at the start of the series and G13BBF is called to perform the filtering.

10.1 Program Text

Program Text (g13bbfe.f90)

10.2 Program Data

Program Data (g13bbfe.d)

10.3 Program Results

Program Results (g13bbfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13BCF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13BCF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13BCF calculates cross-correlations between two time series.

2 Specification

SUBROUTINE G13BCF ( X, Y, NXY, NL, S, R0, R, STAT, IFAIL)
INTEGER | NXY, NL, IFAIL
REAL (KIND=nag_wp) | X(NXY), Y(NXY), S, R0, R(NL), STAT

3 Description

Given two series x 1,x 2,…,xn and y 1,y 2,…,yn the routine calculates the cross-correlations between xt and lagged values of yt:
r xy l=∑t=1 n-l xt-x-y t+l-y- n sxsy ,  l=0,1,…,L
where
x-=∑t= 1 n xt n
sx 2=∑t=1 n xt-x- 2 n
and similarly for y.
The ratio of standard deviations sy/sx is also returned, and a portmanteau statistic is calculated:
STAT=n∑l=1 L r xy l 2.
Provided n is large, L much less than n, and both xt,yt are samples of series whose true autocorrelation functions are zero, then, under the null hypothesis that the true cross-correlations between the series are zero, STAT has a χ 2-distribution with L degrees of freedom. Values of STAT in the upper tail of this distribution provide evidence against the null hypothesis.

4 References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day

5 Arguments

1:   X NXY – REAL (KIND=nag_wp) arrayInput
On entry: the n values of the x series.
2:   Y NXY – REAL (KIND=nag_wp) arrayInput
On entry: the n values of the y series.
3:   NXY – INTEGERInput
On entry: n, the length of the time series.
Constraint: NXY≥2.
4:   NL – INTEGERInput
On entry: L, the maximum lag for calculating cross-correlations.
Constraint: 1≤NL<NXY.
5:   S – REAL (KIND=nag_wp)Output
On exit: the ratio of the standard deviation of the y series to the standard deviation of the x series, sy/sx.
6:   R0 – REAL (KIND=nag_wp)Output
On exit: the cross-correlation between the x and y series at lag zero.
7:   R NL – REAL (KIND=nag_wp) arrayOutput
On exit: R l contains the cross-correlations between the x and y series at lags L, r xy l, for l=1,2,…,L.
8:   STAT – REAL (KIND=nag_wp)Output
On exit: the statistic for testing for absence of cross-correlation.
9:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | NXY≤1,
or | NL<1,
or | NL≥NXY.
IFAIL=2
One or both of the x and y series have zero variance and hence cross-correlations cannot be calculated.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

All computations are believed to be stable.

8 Parallelism and Performance

G13BCF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13BCF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

If n<100, or L<10 log n then the autocorrelations are calculated directly and the time taken by G13BCF is approximately proportional to nL, otherwise the autocorrelations are calculated by utilizing fast Fourier transforms (FFTs) and the time taken is approximately proportional to n log n. If FFTs are used then G13BCF internally allocates approximately 6 n real elements.

10 Example

This example reads two time series of length 20. It calculates and prints the cross-correlations up to lag 15 for the first series leading the second series and then for the second series leading the first series.

10.1 Program Text

Program Text (g13bcfe.f90)

10.2 Program Data

Program Data (g13bcfe.d)

10.3 Program Results

Program Results (g13bcfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13BDF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13BDF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13BDF calculates preliminary estimates of the parameters of a transfer function model.

2 Specification

SUBROUTINE G13BDF ( R0, R, NL, NNA, S, NWDS, WA, IWA, WDS, ISF, IFAIL)
INTEGER | NL, NNA(3), NWDS, IWA, ISF(2), IFAIL
REAL (KIND=nag_wp) | R0, R(NL), S, WA(IWA), WDS(NWDS)

3 Description

G13BDF calculates estimates of parameters δ 1,δ 2,…,δp, ω 0,ω 1,…,ωq in the transfer function model
yt=δ 1y t-1+δ 2y t-2+⋯+δpy t-p+ω 0x t-b-ω 1x t-b-1-⋯-ωqx t-b-q
given cross-correlations between the series xt and lagged values of yt:
r xy l,  l=0,1,…,L
and the ratio of standard deviations sy/sx, as supplied by G13BCF.
It is assumed that the series xt used to calculate the cross-correlations is a sample from a time series with true autocorrelations of zero. Otherwise the cross-correlations between the series bt and at, as defined in the description of G13BAF, should be used in place of those between yt and xt.
The estimates are obtained by solving for δ 1,δ 2,…,δp the equations
r xy b+q+j=δ 1r xy b+q+j-1+⋯+δpr xy b+q+j-p,  j=1,2,…,p
then calculating
ωi = ± sy / sx r xy b+i - δ 1 r xy b+i- 1 - ⋯ - δp r xy b+i-p ,   i= 0,1,…,q
where the ‘+’ is used for ω 0 and ‘-’ for ωi, i>0.
Any value of r xy l arising in these equations for l<b is taken as zero. The parameters δ 1,δ 2,…,δp are checked as to whether they satisfy the stability criterion.

4 References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day

5 Arguments

1:   R0 – REAL (KIND=nag_wp)Input
On entry: the cross-correlation between the two series at lag 0, r xy 0.
Constraint: -1.0≤R0≤1.0.
2:   R NL – REAL (KIND=nag_wp) arrayInput
On entry: the cross-correlations between the two series at lags 1 to L, r xy l, for l=1,2,…,L.
Constraint: -1.0≤R i≤1.0, for i=1,2,…,NL.
3:   NL – INTEGERInput
On entry: L, the number of lagged cross-correlations in the array R.
Constraint: NL≥max NNA 1+NNA 2+NNA 3,1.
4:   NNA 3 – INTEGER arrayInput
On entry: the transfer function model orders in the standard form b,q,p (i.e., delay time, number of moving-average MA-like followed by number of autoregressive AR-like parameters).
Constraint: NNA i≥0, for i=1,2,3.
5:   S – REAL (KIND=nag_wp)Input
On entry: the ratio of the standard deviation of the y series to that of the x series, sy/sx.
Constraint: S>0.0.
6:   NWDS – INTEGERInput
On entry: the exact number of parameters in the transfer function model.
Constraint: NWDS=NNA 2+NNA 3+1.
7:   WA IWA – REAL (KIND=nag_wp) arrayWorkspace
8:   IWA – INTEGERInput
On entry: the dimension of the array WA as declared in the (sub)program from which G13BDF is called.
Constraint: IWA≥NNA 3×NNA 3+1.
9:   WDS NWDS – REAL (KIND=nag_wp) arrayOutput
On exit: the preliminary estimates of the parameters of the transfer function model in the order of q+1 MA-like parameters followed by the p AR-like parameters. If the estimation of either type of parameter fails then these arguments are set to 0.0.
10:   ISF 2 – INTEGER arrayOutput
On exit: indicators of the success of the estimation of MA-like and AR-like parameters respectively. A value 0 indicates that there are no parameters of that type to be estimated. A value of 1 or -1 indicates that there are parameters of that type in the model and the estimation of that type has been successful or unsuccessful respectively. Note that there is always at least one MA-like parameter in the model.
11:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | NNA i<0, for i=1,2,3,
or | NL<max NNA 1+NNA 2+NNA 3,1,
or | R0<-1.0 or R0>1.0,
or | R i<-1.0 or R i>1.0, for some i=1,2,…,NL,
or | S≤0.0,
or | NWDS≠NNA 2+NNA 3+1,
or | IWA<NNA 3×NNA 3+1.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Equations used in the computations may become unstable, in which case results are reset to zero with array ISF values set accordingly.

8 Parallelism and Performance

G13BDF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13BDF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

If NNA 3>0,a local workspace array of fixed length is allocated internally by G13BDF. The total size of this array amounts to NNA 3 integer elements and NNA 3×NNA 3+1 real elements.
The time taken by G13BDF is roughly proportional to NWDS 3.

10 Example

This example reads the cross-correlations between two series at lags 0 to 6. It then reads a 3,2,1 transfer function model and calculates and prints the preliminary estimates of the parameters of the model.

10.1 Program Text

Program Text (g13bdfe.f90)

10.2 Program Data

Program Data (g13bdfe.d)

10.3 Program Results

Program Results (g13bdfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13BEF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13BEF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
▸▿ 3 Description
3.1 The Multi-input Model
3.2 The Estimation Criterion
3.3 The Estimation Procedure
3.4 Further Results
3.5 Forecasting Information
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13BEF fits a multi-input model relating one output series to the input series with a choice of three different estimation criteria: nonlinear least squares, exact likelihood and marginal likelihood. When no input series are present, G13BEF fits a univariate ARIMA model.

2 Specification

SUBROUTINE G13BEF ( MR, NSER, MT, PARA, NPARA, KFC, NXXY, XXY, LDXXY, KEF, NIT, KZSP, ZSP, ITC, SD, CM, LDCM, S, D, NDF, KZEF, RES, STTF, ISTTF, NSTTF, WA, IWA, MWA, IMWA, KPRIV, IFAIL)
INTEGER | MR(7), NSER, MT(4,NSER), NPARA, KFC, NXXY, LDXXY, KEF, NIT, KZSP, ITC, LDCM, NDF, KZEF, ISTTF, NSTTF, IWA, MWA(IMWA), IMWA, KPRIV, IFAIL
REAL (KIND=nag_wp) | PARA(NPARA), XXY(LDXXY,NSER), ZSP(4), SD(NPARA), CM(LDCM,NPARA), S, D, RES(NXXY), STTF(ISTTF), WA(IWA)

3 Description

3.1 The Multi-input Model

The output series yt, for t=1,2,…,n, is assumed to be the sum of (unobserved) components z i,t which are due respectively to the inputs x i,t, for i=1,2,…,m.
Thus yt=z 1,t+⋯+z m,t+nt where nt is the error, or output noise component.
A typical component zt may be either
(a) a simple regression component, zt=ω xt (here xt is called a simple input), or
(b) a transfer function model component which allows for the effect of lagged values of the variable, related to xt by
zt = δ 1 z t-1 + δ 2 z t-2 + ⋯ + δp z t-p + ω 0 x t-b - ω 1 x t-b-1 - ⋯ - ωq x t-b-q .
The noise nt is assumed to follow a (possibly seasonal) ARIMA model, i.e., may be represented in terms of an uncorrelated series, at, by the hierarchy of equations
(i) | ∇d ∇sD nt = c+wt
(ii) | wt = Φ 1 w t-s + Φ 2 w t-2×s +⋯+ ΦP w t-P×s + et - Θ 1 e t-s - Θ 2 e t-2×s -⋯- ΘQ e t-Q×s
(iii) | et = ϕ 1 e t-1 + ϕ 2 e t-2 +⋯+ ϕp e t-p +at - θ 1 a t-1 - θ 2 a t-2 -⋯- θq a t-q
as outlined in Section 3 in G13AEF.
Note: the orders p,q appearing in each of the transfer function models and the ARIMA model are not necessarily the same; ∇d∇sD nt is the result of applying non-seasonal differencing of order d and seasonal differencing of seasonality s and order D to the series nt: the differenced series is then of length N=n-d-s×D; the constant term parameter c may optionally be held fixed at its initial value (usually, but not necessarily zero) rather than being estimated.
For the purpose of defining an estimation criterion it is assumed that the series at is a sequence of independent Normal variates having mean 0 and variance σa 2. An allowance has to be made for the effects of unobserved data prior to the observation period. For the noise component an allowance is always made using a form of backforecasting.
For each transfer function input, you have to decide what values are to be assumed for the pre-period terms z 0,z-1,…,z 1-p and x 0,x-1,…,x 1-b-q which are in theory necessary to re-create the component series z 1,z 2,…,zn, during the estimation procedure.
The first choice is to assume that all these values are zero. In this case, in order to avoid undesirable transient distortion of the early values z 1,z 2,…, you are advised first to correct the input series xt by subtracting from all the terms a suitable constant to make the early values x 1,x 2,…, close to zero. The series mean x- is one possibility, but for a series with strong trend the constant might be simply x 1.
The second choice is to treat the unknown pre-period terms as nuisance parameters and estimate them along with the other parameters. This choice should be used with caution. For example, if p=1 and b=q=0, it is equivalent to fitting to the data a decaying geometric curve of the form A δt, for t=1,2,…, along with the other inputs, this being the form of the transient. If the output yt contains a strong trend of this form, which is not otherwise represented in the model, it will have a tendency to influence the estimate of δ away from the value appropriate to the transfer function model.
In most applications the first choice should be adequate, with the option possibly being used as a refinement at the end of the modelling process. The number of nuisance parameters is then max p,b+q, with a corresponding loss of degrees of freedom in the residuals. If you align the input xt with the output by using in its place the shifted series x t-b, then setting b=0 in the transfer function model, there is some improvement in efficiency. On some occasions when the model contains two or more inputs, each with estimation of pre-period nuisance parameters, these parameters may be co-linear and lead to failure of the routine. The option must then be ‘switched off’ for one or more inputs.

3.2 The Estimation Criterion

This is a measure of how well a proposed set of parameters in the transfer function and noise ARIMA models matches the data. The estimation routine searches for parameter values which minimize this criterion. For a proposed set of parameter values it is derived by calculating
(i) | the components z 1,t,z 2,t,…,z m,t as the responses to the input series x 1,t,x 2,t…,x m,t using the equations (a) or (b) above,
(ii) the discrepancy between the output and the sum of these components, as the noise
n t = y t - z 1 , t + z 2 , t + ⋯ + z m , t ,
(iii) | the residual series at from nt by reversing the recursive equations (i), (ii) and (iii) above.
This last step again requires treatment of the effect of unknown pre-period values of nt and other terms in the equations regenerating at. This is identical to the treatment given in Section 3 in G13AEF, and leads to a criterion which is a sum of squares function S, of the residuals at. It may be shown that the finite algorithm presented there is equivalent to taking the infinite set of past values n 0,n-1,n-2,…, as (linear) nuisance parameters. There is no loss of degrees of freedom however, because the sum of squares function S may be expressed as including the corresponding set of past residuals; see page 273 of Box and Jenkins (1976), who prove that
S=∑-∞n at 2.
The function D=S is the first of the three possible criteria, and is quite adequate for moderate to long series with no seasonal parameters. The second is the exact likelihood criterion which considers the past set n 0,n-1,n-2 not as simple nuisance parameters, but as unobserved random variables with known distribution. Calculation of the likelihood of the observed set n 1,n 2,…,nn requires theoretical integration over the range of the past set. Fortunately this yields a criterion of the form D=M×S (whose minimization is equivalent to maximizing the exact likelihood of the data), where S is exactly as before, and the multiplier M is a function calculated from the ARIMA model parameters. The value of M is always ≥1, and M tends to 1 for any fixed parameter set as the sample size n tends to ∞. There is a moderate computational overhead in using this option, but its use avoids appreciable bias in the ARIMA model parameters and yields a better conditioned estimation problem.
The third criterion of marginal likelihood treats the coefficients of the simple inputs in a manner analogous to that given to the past set n 0,n-1,n-2,…. These coefficients, together with the constant term c used to represent the mean of wt, are in effect treated as random variables with highly dispersed distributions. This leads to the criterion D=M×S again, but with a different value of M which now depends on the simple input series values xt. In the presence of a moderate to large number of simple inputs, the marginal likelihood criterion can counteract bias in the ARIMA model parameters which is caused by estimation of the simple inputs. This is particularly important in relatively short series.
G13BEF can be used with no input series present, to estimate a univariate ARIMA model for the output alone. The marginal likelihood criterion is then distinct from exact likelihood only if a constant term is being estimated in the model, because this is treated as an implicit simple input.

3.3 The Estimation Procedure

This is the minimization of the estimation criterion or objective function D (for deviance). The routine uses an extension of the algorithm of Marquardt (1963). The step size in the minimization is inversely related to a parameter α, which is increased or decreased by a factor β at successive iterations, depending on the progress of the minimization. Convergence is deemed to have occurred if the fractional reduction of D in successive iterations is less than a value γ, while α<1.
Certain model parameters (in fact all excluding the ωs) are subject to stability constraints which are checked throughout to within a specified tolerance multiple δ of machine accuracy. Using the least squares criterion, the minimization may halt prematurely when some parameters ‘stick’ at a constraint boundary. This can happen particularly with short seasonal series (with a small number of whole seasons). It will not happen using the exact likelihood criterion, although convergence to a point on the boundary may sometimes be rather slow, because the criterion function may be very flat in such a region. There is also a smaller risk of a premature halt at a constraint boundary when marginal likelihood is used.
A positive, or zero number of iterations can be specified. In either case, the value D of the objective function at iteration zero is presented at the initial parameter values, except for estimation of any pre-period terms for the input series, backforecasts for the noise series, and the coefficients of any simple inputs, and the constant term (unless this is held fixed).
At any later iteration, the value of D is computed after re-estimation of the backforecasts to their optimal values, corresponding to the model parameters presented at that iteration. This is not true for any pre-period terms for the input series which, although they are updated from the previous iteration, may not be precisely optimal for the parameter values presented, unless convergence of those parameters has occurred. However, in the case of marginal likelihood being specified, the coefficients of the simple inputs and the constant term are also re-estimated together with the backforecasts at each iteration, to values which are optimal for the other parameter values presented.

3.4 Further Results

The residual variance is taken as erv= Sdf , where df=N-(total number of parameters estimated), is the residual degrees of freedom. The pre-period nuisance parameters for the input series are included in the reduction of df, as is the constant if it is estimated.
The covariance matrix of the vector of model parameter estimates is given by
erv×H-1
where H is the linearized least squares matrix taken from the final iteration of the algorithm of Marquardt. From this expression are derived the vector of standard deviations, and the correlation matrix of parameter estimates. These are approximations which are only valid asymptotically, and must be treated with great caution when the parameter estimates are close to their constraint boundaries.
The residual series at is available upon completion of the iterations over the range t=1+d+s×D,…,n corresponding to the differenced noise series wt.
Because of the algorithm used for backforecasting, these are only true residuals for t≥1+q+s×Q-p-s×P-d-s×D, provided this is positive. Estimation of pre-period terms for the inputs will also tend to reduce the magnitude of the early residuals, sometimes severely.
The model component series z 1,t,…,z m,t and nt may optionally be returned in place of the supplied series values, in order to assess the effects of the various inputs on the output.

3.5 Forecasting Information

For the purpose of constructing forecasts of the output series at future time points t=n+1,n+2,… using G13BHF, it is not necessary to use the whole set of observations yt and x 1,t,x 2,t,…,x m,t, for t=1,2,…,m. It is sufficient to retain a limited set of quantities constituting the ‘state set’ as follows: for each series which appears with lagged subscripts in equations (a), (b), (i), (ii) and (iii) above, include the values at times n+1-k for k=1 up to the maximum lag associated with that series in the equations. Note that (i) implicitly includes past values of nt and intermediate differences of nt such as ∇d-1∇sD.
If later observations of the series become available, it is possible to update the state set (without re-estimating the model) using G13BGF. If time series data is supplied with a previously estimated model, it is possible to construct the state set (and forecasts) using G13BJF.

4 References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day
Marquardt D W (1963) An algorithm for least squares estimation of nonlinear parameters J. Soc. Indust. Appl. Math. 11 431

5 Arguments

1:   MR 7 – INTEGER arrayInput
On entry: the orders vector p,d,q,P,D,Q,s of the ARIMA model for the output noise component.
p, q, P and Q refer respectively to the number of autoregressive ϕ, moving average θ, seasonal autoregressive Φ and seasonal moving average Θ parameters.
d, D and s refer respectively to the order of non-seasonal differencing, the order of seasonal differencing and the seasonal period.
Constraints:
  • p, d, q, P, D, Q, s≥0;
  • p+q+P+Q>0;
  • s≠1;
  • if s=0, P+D+Q=0;
  • if s>1, P+D+Q>0;
  • d+s×P+D≤n;
  • p+d-q+s×P+D-Q≤n.
2:   NSER – INTEGERInput
On entry: the total number of input and output series. There may be any number of input series (including none), but always one output series.
Constraints:
  • NSER≥1;
  • if there are no parameters in the model (that is, p=q=P=Q=0 and KFC=0), NSER>1.
3:   MT 4 NSER – INTEGER arrayInput
On entry: the transfer function model orders b, p and q of each of the input series. The order arguments for input series i are held in column i. Row 1 holds the value bi, row 2 holds the value qi and row 3 holds the value pi. For a simple input, bi=qi=pi=0.
Row 4 holds the value ri, where ri=1 for a simple input, ri=2 for a transfer function input for which no allowance is to be made for pre-observation period effects, and ri=3 for a transfer function input for which pre-observation period effects will be treated by estimation of appropriate nuisance parameters.
When ri=1, any nonzero contents of rows 1, 2, and 3 of column i are ignored.
Constraint: MT 4 i=1, ​2​ or ​3, for i=1,2,…,NSER-1.
4:   PARA NPARA – REAL (KIND=nag_wp) arrayInput/Output
On entry: initial values of the multi-input model parameters. These are in order, firstly the ARIMA model parameters: p values of ϕ parameters, q values of θ parameters, P values of Φ parameters and Q values of Θ parameters. These are followed by initial values of the transfer function model parameters ω 0,ω 1,…,ω q 1, δ 1,δ 2,…,δ p 1 for the first of any input series and similarly for each subsequent input series. The final component of PARA is the initial value of the constant c, whether it is fixed or is to be estimated.
On exit: the latest values of the estimates of these parameters.
5:   NPARA – INTEGERInput
On entry: the exact number of ϕ,θ,Φ,Θ, ω,δ and c parameters.
Constraint: NPARA=p+q+P+Q+NSER+∑pi+qi, the summation being over all the pi≠qi supplied in MT. c must be included, whether fixed or estimated.
6:   KFC – INTEGERInput
On entry: must be set to 0 if the constant c is to remain fixed at its initial value, and 1 if it is to be estimated.
Constraint: KFC=0 or 1.
7:   NXXY – INTEGERInput
On entry: the (common) length of the original, undifferenced input and output time series.
8:   XXY LDXXYNSER – REAL (KIND=nag_wp) arrayInput/Output
On entry: the columns of XXY must contain the NXXY original, undifferenced values of each of the input series and the output series xt in that order.
On exit: if KZEF=0, XXY remains unchanged on exit.
If KZEF≠0, the columns of XXY hold the corresponding values of the input component series zt in place of xt and the output noise component nt in place of yt, in that order.
9:   LDXXY – INTEGERInput
On entry: the first dimension of the array XXY as declared in the (sub)program from which G13BEF is called.
Constraint: LDXXY≥NXXY.
10:   KEF – INTEGERInput
On entry: indicates the likelihood option.
KEF=1
Gives least squares.
KEF=2
Gives exact likelihood.
KEF=3
Gives marginal likelihood.
Constraint: KEF=1, 2 or 3.
11:   NIT – INTEGERInput
On entry: the maximum required number of iterations.
NIT=0
No change is made to any of the model parameters in array PARA except that the constant c (if KFC=1) and any ω relating to simple input series are estimated. (Apart from these, estimates are always derived for the nuisance parameters relating to any backforecasts and any pre-observation period effects for transfer function inputs.)
Constraint: NIT≥0.
12:   KZSP – INTEGERInput
On entry: must be set to 1 if the routine is to use the input values of ZSP in the minimization procedure, and to any other value if the default values of ZSP are to be used.
13:   ZSP 4 – REAL (KIND=nag_wp) arrayInput/Output
On entry: if KZSP=1, then ZSP must contain the four values used to control the strategy of the search procedure.
ZSP 1
Contains α, the value used to constrain the magnitude of the search procedure steps.
ZSP 2
Contains β, the multiplier which regulates the value of α.
ZSP 3
Contains δ, the value of the stationarity and invertibility test tolerance factor.
ZSP 4
Contains γ, the value of the convergence criterion.
If KZSP≠1 before entry, default values of ZSP are supplied by the routine. These are 0.01, 10.0, 1000.0 and max 100×machine precision,0.0000001, respectively.
On exit: contains the values, default or otherwise, used by the routine.
Constraint: if KZSP=1, ZSP 1>0.0, ZSP 2>1.0, ZSP 3≥1.0, 0≤ZSP 4<1.0.
14:   ITC – INTEGEROutput
On exit: the number of iterations carried out.
ITC=-1
Indicates that the only estimates obtained up to this point have been for the nuisance parameters relating to backforecasts, unless the marginal likelihood option is used, in which case estimates have also been obtained for simple input coefficients ω and for the constant c (if KFC=1). This value of ITC usually indicates a failure in a consequent step of estimating transfer function input pre-observation period nuisance parameters.
ITC=0
Indicates that estimates have been obtained up to this point for the constant c (if KFC=1), for simple input coefficients ω and for the nuisance parameters relating to the backforecasts and to transfer function input pre-observation period effects.
15:   SD NPARA – REAL (KIND=nag_wp) arrayOutput
On exit: the NPARA values of the standard deviations corresponding to each of the parameters in PARA. When the constant is fixed its standard deviation is returned as zero. When the values of PARA are valid, the values of SD are usually also valid. However, if an exit value of IFAIL=3, 8 or 10, then the contents of SD will be indeterminate.
16:   CM LDCMNPARA – REAL (KIND=nag_wp) arrayOutput
On exit: the first NPARA rows and columns of CM contain the correlation coefficients relating to each pair of parameters in PARA. All coefficients relating to the constant will be zero if the constant is fixed. The contents of CM will be indeterminate under the same conditions as SD.
17:   LDCM – INTEGERInput
On entry: the first dimension of the array CM as declared in the (sub)program from which G13BEF is called.
Constraint: LDCM≥NPARA.
18:   S – REAL (KIND=nag_wp)Output
On exit: the residual sum of squares, S, at the latest set of valid parameter estimates.
19:   D – REAL (KIND=nag_wp)Output
On exit: the objective function, D, at the latest set of valid parameter estimates.
20:   NDF – INTEGEROutput
On exit: the number of degrees of freedom associated with S.
21:   KZEF – INTEGERInput
On entry: must not be set to 0, if the values of the input component series zt and the values of the output noise component nt are to overwrite the contents of XXY on exit, and must be set to 0 if XXY is to remain unchanged.
22:   RES NXXY – REAL (KIND=nag_wp) arrayOutput
On exit: the values of the residuals relating to the differenced values of the output series. The remainder of the first NXXY terms in the array will be zero.
23:   STTF ISTTF – REAL (KIND=nag_wp) arrayOutput
On exit: the NSTTF values of the state set array.
24:   ISTTF – INTEGERInput
On entry: the dimension of the array STTF as declared in the (sub)program from which G13BEF is called.
Constraint: ISTTF≥P×s+d+D×s+q+max p,Q×s+ncg, where ncg=∑bi+qi+pi over all input series for which ri>1.
25:   NSTTF – INTEGEROutput
On exit: the number of values in the state set array STTF.
26:   WA IWA – REAL (KIND=nag_wp) arrayWorkspace
27:   IWA – INTEGERInput
On entry: the dimension of the array WA as declared in the (sub)program from which G13BEF is called.
It is not practical to outline a method for deriving the exact minimum permissible value of IWA, but the following gives a reasonably good conservative approximation. (It should be noted that if IWA is too small (but not grossly so) then the exact minimum is returned in MWA i and is also printed if KPRIV≠0.)
Let q′=q+Q×s and d′=d+D×s where the orders of the output noise model are p, d, q, P, D, Q, s.
Let there be l input series, where l=NSER-1.
Let
m xi = max bi + qi ,pi , if ​ ri=3 , for ​ i=1,2…,l m xi = 0 , if ​ ri≠3 , for ​ i=1,2…,l
where the transfer function model orders for input i are given by bi, qi, pi, ri.
Let qx=max q′,m x 1,m x 2,…,m xl.
Let ncd=NPARA+KFC+qx+∑i=1 l m xi and nce=NXXY+d′+6×qx.
Finally, let ncf=NSER, and then increment ncf by 1 every time any of the following conditions is satisfied. (The last six conditions should be applied separately to each input series, so that, for example, if we have two input series and if p 1>0 and p 2>0 then ncf is incremented by 2.)
The conditions are:
p>0 q>0 P>0 Q>0 qx>0 KFC>0 p>0 q>0 P>0 Q>0 and ​q>0​ and ​KEF>1. p>0 q>0 P>0 Q>0 and ​KFC>0​ and ​KEF=3. m xi>0 pi>0 p>0 q>0 P>0 Q>0 and ​ri=1​ and ​KEF>3​ separately, for ​i=1,2,…,l.
Then IWA≥2× ncd 2+nce×ncf+4.
28:   MWA IMWA – INTEGER arrayWorkspace
29:   IMWA – INTEGERInput
On entry: the dimension of the array MWA as declared in the (sub)program from which G13BEF is called.
Constraint: IMWA≥16×NSER+7×ncd+3×NPARA+3×KFC+27, where the derivation of ncd is shown under IWA.
If IMWA is too small then the exact minimum needed is returned in IMWA and if KPRIV≠0 it is also printed.
30:   KPRIV – INTEGERInput
On entry: must not be set to 0, if it is required to monitor the course of the optimization or to print out the requisite minimum values of IWA or IMWA in the event of an error of the type IFAIL=6 or 7. The course of the optimization is monitored by printing out at each iteration the iteration count (ITC), the residual sum of squares (S), the objective function (D) and a description and value for each of the parameters in the PARA array. The descriptions are PHI for ϕ, THETA for θ, SPHI for Φ, STHETA for Θ, OMEGA/SI for ω in a simple input, OMEGA for ω in a transfer function input, DELTA for δ and CONSTANT for c. In addition SERIES 1, SERIES 2, etc. indicate the input series relevant to the OMEGA and DELTA parameters.
KPRIV must be set to 0 if the print-out of the above information is not required.
31:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if IFAIL≠0 on exit, the recommended value is -1. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Note: G13BEF may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the routine:
IFAIL=1
On entry, | KFC<0,
or | KFC>1,
or | LDXXY<NXXY,
or | LDCM<NPARA,
or | KEF<1,
or | KEF>3,
or | NIT<0,
or | NSER<1,
or | NSER=1 and there are no parameters in the model (p=q=P=Q=0 and KFC=0).
IFAIL=2
On entry, there is inconsistency between NPARA and KFC on the one hand and the orders in arrays MR and MT on the other, or one of the ri, stored in MT 4 i≠1, 2 or 3.
IFAIL=3
On entry or during execution, one or more sets of δ parameters do not satisfy the stationarity or invertibility test conditions.
IFAIL=4
On entry, | when KZSP=1, ZSP 1≤0.0,
or | ZSP 2≤1.0,
or | ZSP 3<1.0,
or | ZSP 4<0.0,
or | ZSP 4≥1.0.
IFAIL=5
On entry, IWA is too small by a considerable margin. No information is supplied about the requisite minimum size.
IFAIL=6
On entry, IWA is too small, but the requisite minimum size is returned in MWA 1, which is printed if KPRIV≠0.
IFAIL=7
On entry, IMWA is too small, but the requisite minimum size is returned in MWA 1, which is printed if KPRIV≠0.
IFAIL=8
Unable to calculate the latest parameter estimates.
IFAIL=9
This indicates a failure in the inversion of the second derivative matrix. This is needed in the calculation of the correlation matrix and the standard deviations of the parameter estimates.
IFAIL=10
On entry or during execution, one or more sets of the ARIMA (ϕ, θ, Φ or Θ) parameters do not satisfy the stationarity or invertibility test conditions.
IFAIL=11
On entry, ISTTF is too small. The state set information will not be produced and if KZEF≠0 array XXY will remain unchanged. All other arguments will be produced correctly.
IFAIL=12
The routine has failed to converge after NIT iterations. If steady decreases in the objective function, D, were monitored up to the point where this exit occurred, then the exit probably occurred because NIT was set too small, so the calculations should be restarted from the final point held in PARA.
IFAIL=13
On entry, ISTTF is too small (see IFAIL=11) and NIT iterations were carried out without the convergence conditions being satisfied (see IFAIL=12).
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The computation used is believed to be stable.

8 Parallelism and Performance

G13BEF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13BEF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

The time taken by G13BEF is approximately proportional to NXXY×ITC×NPARA 2.

10 Example

After the full 11 iterations, the following are computed and printed out: the final values of the PARA parameters and their standard errors, the correlation matrix, the residuals for the 36 differenced values, the values of zt and nt, the values of the state set and the number of degrees of freedom.

10.1 Program Text

Program Text (g13befe.f90)

10.2 Program Data

Program Data (g13befe.d)

10.3 Program Results

Program Results (g13befe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13BGF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13BGF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13BGF accepts a series of new observations of an output time series and any associated input time series, for which a multi-input model is already fully specified, and updates the ‘state set’ information for use in constructing further forecasts.
The previous specification of the multi-input model will normally have been obtained by using G13BEF to estimate the relevant transfer function and ARIMA parameters. The supplied state set will originally have been produced by G13BEF (or possibly G13BJF), but may since have been updated by G13BGF.

2 Specification

SUBROUTINE G13BGF ( STTF, NSTTF, MR, NSER, MT, PARA, NPARA, NNV, XXYN, LDXXYN, KZEF, RES, WA, IWA, IFAIL)
INTEGER | NSTTF, MR(7), NSER, MT(4,NSER), NPARA, NNV, LDXXYN, KZEF, IWA, IFAIL
REAL (KIND=nag_wp) | STTF(NSTTF), PARA(NPARA), XXYN(LDXXYN,NSER), RES(NNV), WA(IWA)

3 Description

The multi-input model is specified in Section 3 in G13BEF. The form of these equations required to update the state set is as follows:
zt=δ 1z t-1+δ 2z t-2+⋯+δpz t-p+ω 0x t-b-ω 1x t-b-1-⋯-ωqx t-b-q
the transfer models which generate input component values z i,t from one or more inputs x i,t,
nt=yt-z 1,t-z 2,t-⋯-z m,t
which generates the output noise component from the output yt and the input components, and
wt =∇d∇sD nt-c et =wt-Φ 1w t-s-Φ 2w t-2×s-⋯-ΦPw t-P×s+Θ 1e t-s+Θ 2e t-2×s+⋯+ΘQe t-Q×s at =et-ϕ 1e t-1-ϕ 2e t-2-⋯-ϕpe t-p+θ 1a t-1+θ 2a t-2+⋯+θqa t-q
the ARIMA model for the output noise which generates the residuals at.
The state set (as also given in Section 3 in G13BEF) is the collection of terms
z n+1-k,x n+1-k,n n+1-k,w n+1-k,e n+1-k  and  a n+1-k
for k=1 up to the maximum lag associated with each of these series respectively, in the above model equations. n is the latest time point of the series from which the state set has been generated.
The routine accepts further values of the series yt, x 1,t,x 2,t,…,x m,t, for t=n+1,…,n+l, and applies the above model equations over this time range, to generate new values of the various model components, noise series and residuals. The state set is reconstructed, corresponding to the latest time point n+l, the earlier values being discarded.
The set of residuals corresponding to the new observations may be of use in checking that the new observations conform to the previously fitted model. The components of the new observations of the output series which are due to the various inputs, and the noise component, are also optionally returned.
The parameters of the model are not changed in this routine.

4 References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day

5 Arguments

1:   STTF NSTTF – REAL (KIND=nag_wp) arrayInput/Output
On entry: the NSTTF values in the state set before updating as returned by G13BEF or G13BJF, or a previous call to G13BGF.
On exit: the state set values after updating.
2:   NSTTF – INTEGERInput
On entry: the exact number of values in the state set array STTF as returned by G13BEF or G13BJF.
3:   MR 7 – INTEGER arrayInput
On entry: the orders vector p,d,q,P,D,Q,s of the ARIMA model for the output noise component.
p, q, P and Q refer respectively to the number of autoregressive ϕ, moving average θ, seasonal autoregressive Φ and seasonal moving average Θ parameters.
d, D and s refer respectively to the order of non-seasonal differencing, the order of seasonal differencing, and the seasonal period.
Constraints:
  • p, d, q, P, D, Q, s≥0;
  • p+q+P+Q>0;
  • s≠1;
  • if s=0, P+D+Q=0;
  • if s>1, P+D+Q>0.
4:   NSER – INTEGERInput
On entry: the total number of input and output series. There may be any number of input series (including none), but only one output series.
5:   MT 4 NSER – INTEGER arrayInput
On entry: the transfer function model orders b, p and q of each of the input series. The data for input series i are held in column i. Row 1 holds the value bi, row 2 holds the value qi and row 3 holds the value pi. For a simple input, bi=qi=pi=0.
Row 4 holds the value ri, where ri=1 for a simple input and ri=2​ or ​3 for a transfer function input. When ri=1 any nonzero contents of rows 1, 2 and 3 of column i are ignored. The choice of ri=2 or ri=3 is an option for use in model estimation and does not affect the operation of G13BGF.
Constraint: MT 4 i=1, 2 or 3, for i=1,2,…,NSER-1.
6:   PARA NPARA – REAL (KIND=nag_wp) arrayInput
On entry: estimates of the multi-input model parameters as returned by G13BEF. These are in order, firstly the ARIMA model parameters: p values of ϕ parameters, q values of θ parameters, P values of Φ parameters and Q values of Θ parameters. These are followed by the transfer function model parameter values ω 0,ω 1,…,ω q 1, δ 1,δ 2,…,δ p 1 for the first of any input series and similarly for each subsequent input series. The final component of PARA is the value of the constant c.
7:   NPARA – INTEGERInput
On entry: the exact number of ϕ, θ, Φ, Θ, ω, δ and c parameters. (c must be included whether its value was previously estimated or was set fixed.)
8:   NNV – INTEGERInput
On entry: the number of new observation sets being used to update the state set, each observation set consisting of a value of the output series and the associated values of each of the input series at a particular time point.
9:   XXYN LDXXYNNSER – REAL (KIND=nag_wp) arrayInput/Output
On entry: the NNV new observation sets being used to update the state set. Column i contains the values of input series i, for i=1,2,…,NSER-1. Column NSER contains the values of the output series. Consecutive rows correspond to increasing time sequence.
On exit: if KZEF=0, XXYN remains unchanged.
If KZEF≠0, the columns of XXYN hold the corresponding values of the input component series zt and the output noise component nt in that order.
10:   LDXXYN – INTEGERInput
On entry: the first dimension of the array XXYN as declared in the (sub)program from which G13BGF is called.
Constraint: LDXXYN≥NNV.
11:   KZEF – INTEGERInput
On entry: must not be set to 0, if the values of the input component series zt and the values of the output noise component nt are to overwrite the contents of XXYN on exit, and must be set to 0 if XXYN is to remain unchanged on exit.
12:   RES NNV – REAL (KIND=nag_wp) arrayOutput
On exit: the values of the residual series at corresponding to the new observations of the output series.
13:   WA IWA – REAL (KIND=nag_wp) arrayWorkspace
14:   IWA – INTEGERInput
On entry: the dimension of the array WA as declared in the (sub)program from which G13BGF is called.
Constraint: IWA≥NNV+2×NSTTF+max NNV,NSTTF+max NNV,ncc, where ncc=4×p+q+P+Q.
15:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, NSTTF is not consistent with the orders in arrays MR and MT.
IFAIL=2
On entry, NPARA is not consistent with the orders in arrays MR and MT.
IFAIL=3
On entry, LDXXYN is too small.
IFAIL=4
On entry, IWA is too small.
IFAIL=5
On entry, one of the ri, stored in MT 4 i, for i=1,2,…,NSER-1 does not equal 1, 2 or 3.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The computations are believed to be stable.

8 Parallelism and Performance

G13BGF is not threaded in any implementation.

9 Further Comments

The time taken by G13BGF is approximately proportional to NNV×NPARA.

10 Example

This example uses the data described in G13BEF in which 40 observations of an output time series and a single input series were processed. In this example a model which included seasonal differencing of order 1 was used. The 10 values of the state set and the 5 final values of PARA then obtained are used as input to this program, together with the values of 4 new observations and the transfer function orders of the input series. The model used is ϕ 1=0.5158, Θ 1=0.9994, ω 0=8.6343, δ 1=0.6726, c=-0.3172.
The following are computed and printed out: the updated state set, the residuals at and the values of the components zt and the output noise component nt corresponding to the new observations.

10.1 Program Text

Program Text (g13bgfe.f90)

10.2 Program Data

Program Data (g13bgfe.d)

10.3 Program Results

Program Results (g13bgfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13BHF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13BHF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13BHF produces forecasts of a time series (the output series) which depends on one or more other (input) series via a multi-input model which will usually have been fitted using G13BEF. The future values of the input series must be supplied. The original observations are not required. G13BHF uses as input either the original state set obtained from G13BEF, or the state set updated by a series of new observations from G13BGF. Standard errors of the forecasts are produced. If future values of some of the input series have been obtained as forecasts using ARIMA models for those series, this may be allowed for in the calculation of the standard errors.

2 Specification

SUBROUTINE G13BHF ( STTF, NSTTF, MR, NSER, MT, PARA, NPARA, NFV, XXYN, LDXXYN, MRX, PARX, LDPARX, RMSXY, KZEF, FVA, FSD, WA, IWA, IFAIL)
INTEGER | NSTTF, MR(7), NSER, MT(4,NSER), NPARA, NFV, LDXXYN, MRX(7,NSER), LDPARX, KZEF, IWA, IFAIL
REAL (KIND=nag_wp) | STTF(NSTTF), PARA(NPARA), XXYN(LDXXYN,NSER), PARX(LDPARX,NSER), RMSXY(NSER), FVA(NFV), FSD(NFV), WA(IWA)

3 Description

The forecasts of the output series yt are calculated, for t=n+1,…,n+L, where n is the latest time point of the observations used to produce the state set and L is the maximum lead time of the forecasts.
First the new input series values xt are used to form the input components zt, for t=n+1,…,n+L, using the transfer function models:
(a) zt=δ 1z t-1+δ 2z t-2+⋯+δpz t-p+ω 0x t-b-ω 1x t-b-1-⋯-ωqx t-b-q.
The output noise component nt is then forecast by setting at=0, for t=n+1,…,n+L, and using the ARIMA model equations:
(b) | et=ϕ 1e t-1+ϕ 2e t-2+⋯+ϕpe t-p+at-θ 1a t-1-θ 2a t-2-⋯-θ 1a t-q
(c) | wt=Φ 1w t-s+Φ 2w t-2×s+⋯+ΦPw t-P×s+et-Θ 1e t-s-Θ 2e t-2×s-⋯-ΘQe t-Q×s
(d) | nt=∇d∇sD -1 wt+c.
This last step of ‘integration’ reverses the process of differencing. Finally the output forecasts are calculated as
yt=z 1,t+z 2,t+⋯+z m,t+nt.
The forecast error variance of y t+l (i.e., at lead time l) is Sl 2, which is the sum of parts which arise from the various input series, and the output noise component. That part due to the output noise is
s nl 2=Vn×ψ 02+ψ 12+⋯+ψ l-1 2,
where Vn is the estimated residual variance of the output noise ARIMA model, and ψ 0,ψ 1,… are the ‘psi-weights’ of this model as defined in Box and Jenkins (1976). They are calculated by applying the equations (b), (c) and (d) above, for t=0,1,…,L, but with artificial values for the various series and with the constant c set to 0. Thus all values of at, et, wt and nt are taken as zero, for t<0; at is taken to be 1, for t=0 and 0, for t>0. The resulting values of nt, for t=0,1,…,L, are precisely ψ 0,ψ 1,…,ψL as required.
Further contributions to Sl 2 come only from those input series, for which future values are forecasts which have been obtained by applying input series ARIMA models. For such a series the contribution is
s zl 2=Vx×ν 02+ν 12+⋯+ν l-1 2,
where Vx is the estimated residual variance of the input series ARIMA model. The coefficients ν 0,ν 1,… are calculated by applying the transfer function model equation (a) above, for t=0,1,…,L, but again with artificial values of the series. Thus all values of zt and xt, for t<0, are taken to be zero, and x 0,x 1,… are taken to be the psi-weight sequence ψ 0,ψ 1,… for the input series ARIMA model. The resulting values of zt, for t=0,1,…,L, are precisely ν 0,ν 1,…,νL as required.
In adding such contributions s zl 2 to s nl 2 to make up the total forecast error variance Sl 2, it is assumed that the various input series with which these contributions are associated are statistically independent of each other.
When using the routine in practice an ARIMA model is required for all the input series. In the case of those inputs for which no such ARIMA model is available (or its effects are to be excluded), the corresponding orders and parameters and the estimated residual variance should be set to zero.

4 References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day

5 Arguments

1:   STTF NSTTF – REAL (KIND=nag_wp) arrayInput
On entry: the NSTTF values in the state set as returned by G13BEF or G13BGF.
2:   NSTTF – INTEGERInput
On entry: the exact number of values in the state set array STTF as returned by G13BEF or G13BGF.
3:   MR 7 – INTEGER arrayInput
On entry: the orders vector p,d,q,P,D,Q,s of the ARIMA model for the output noise component.
p, q, P and Q give respectively the number of autoregressive ϕ, moving average θ, seasonal autoregressive Φ and seasonal moving average Θ parameters.
d, D and s refer respectively to the order of non-seasonal differencing, the order of seasonal differencing, and the seasonal period.
Constraints:
  • p, d, q, P, D, Q, s≥0;
  • p+q+P+Q>0;
  • s≠1;
  • if s=0, P+D+Q=0;
  • if s>1, P+D+Q>0.
4:   NSER – INTEGERInput
On entry: the total number of input and output series. There may be any number of input series (including none), but only one output series.
5:   MT 4 NSER – INTEGER arrayInput
On entry: the transfer function orders b, p and q of each of the input series. The data for input series i are held in column i. Row 1 holds the value bi, row 2 holds the value qi and row 3 holds the value pi. For a simple input, bi=qi=pi=0.
Row 4 holds the value ri, where ri=1 for a simple input, ri=2​ or ​3 for a transfer function input. When ri=1, any nonzero contents of rows 1, 2 and 3 of column i are ignored. The choice of ri=2 or ri=3 is an option for use in model estimation and does not affect the operation of G13BHF.
Constraint: MT 4 i=1, 2 or 3, for i=1,2,…,NSER-1.
6:   PARA NPARA – REAL (KIND=nag_wp) arrayInput
On entry: estimates of the multi-input model parameters as returned by G13BEF. These are in order, firstly the ARIMA model parameters: p values of ϕ parameters, q values of θ parameters, P values of Φ parameters and Q values of Θ parameters. These are followed by the transfer function model parameter values ω 0,ω 1,…,ω q 1, δ 1,δ 2,…,δ p 1 for the first of any input series and similar sets of values for any subsequent input series. The final component of PARA is the constant c.
7:   NPARA – INTEGERInput
On entry: the exact number of ϕ, θ, Φ, Θ, ω, δ and c parameters. (c must be included, whether its value was previously estimated or was set fixed).
8:   NFV – INTEGERInput
On entry: the number of forecast values required.
9:   XXYN LDXXYNNSER – REAL (KIND=nag_wp) arrayInput/Output
On entry: the supplied NFV values for each of the input series required to produce the NFV output series forecasts. Column i contains the values for input series i. Column NSER need not be supplied.
On exit: if KZEF=0, then column NSER of XXYN contains the output series forecast values (as does FVA), but XXYN is otherwise unchanged.
If KZEF≠0, then the columns of XXYN hold the corresponding values of the forecast components zt for each of the input series and the values of the output noise component nt in that order.
10:   LDXXYN – INTEGERInput
On entry: the first dimension of the array XXYN as declared in the (sub)program from which G13BHF is called.
Constraint: LDXXYN≥NFV.
11:   MRX 7 NSER – INTEGER arrayInput/Output
On entry: the orders array for each of the input series ARIMA models. Thus, column i contains values of p, d, q, P, D, Q, s for input series i. In the case of those inputs for which no ARIMA model is available, the corresponding orders should be set to 0. (The model for any input series only affects the standard errors of the forecast values.)
On exit: unchanged, apart from column NSER which is used for workspace.
12:   PARX LDPARXNSER – REAL (KIND=nag_wp) arrayInput
On entry: values of the parameters (ϕ, θ, Φ and Θ) for each of the input series ARIMA models. Thus column i contains MRX 1 i values of ϕ parameters, MRX 3 i values of θ parameters, MRX 4 i values of Φ parameters and MRX 6 i values of Θ parameters – in that order.
Values in the columns relating to those input series for which no ARIMA model is available are ignored. (The model for any input series only affects the standard errors of the forecast values.)
13:   LDPARX – INTEGERInput
On entry: the first dimension of the array PARX as declared in the (sub)program from which G13BHF is called.
Constraint: LDPARX≥ncd, where ncd is the maximum number of parameters in any of the input series ARIMA models. If there are no input series, LDPARX≥1.
14:   RMSXY NSER – REAL (KIND=nag_wp) arrayInput
On entry: the estimated residual variances for each input series ARIMA model followed by that for the output noise ARIMA model. In the case of those inputs for which no ARIMA model is available, or when its effects are to be excluded in the calculation of forecast standard errors, the corresponding entry of RMSXY should be set to 0.
15:   KZEF – INTEGERInput
On entry: must not be set to 0, if the values of the input component series zt and the values of the output noise component nt are to overwrite the contents of XXYN on exit, and must be set to 0 if XXYN is to remain unchanged on exit, apart from the appearance of the forecast values in column NSER.
16:   FVA NFV – REAL (KIND=nag_wp) arrayOutput
On exit: the required forecast values for the output series.
17:   FSD NFV – REAL (KIND=nag_wp) arrayOutput
On exit: the standard errors for each of the forecast values.
18:   WA IWA – REAL (KIND=nag_wp) arrayWorkspace
19:   IWA – INTEGERInput
On entry: the dimension of the array WA as declared in the (sub)program from which G13BHF is called.
A good, slightly conservative approximation to the required size of IWA is given by
IWA≥4×NSTTF+NFV+ncf
where ncf is the largest number of ARIMA parameters in any one of the input or output series.
An exact value for the required size of IWA can be calculated as follows:
Let ncg=max pi,
nch=max bi+qi,
nci=max bi+qi+pi,
over each of the transfer function input series for which ri>1, where bi, qi, pi are the orders held in rows 1 to 3 of array MT.
Let ncj=1+nci,
nck=NFV+max ncg,nch,
ncl=max NSTTF,ncf,ncj,nck,
ncm=max NSTTF+4×ncf,ncl,
then IWA≥ncm+3×ncl+NFV.
20:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, NSTTF is not consistent with the orders in arrays MR and MT.
IFAIL=2
On entry, NPARA is not consistent with the orders in arrays MR and MT.
IFAIL=3
On entry, LDXXYN is too small.
IFAIL=4
On entry, IWA is too small.
IFAIL=5
On entry, LDPARX is too small.
IFAIL=6
On entry, one of the ri, stored in MT 4 i, for i=1,2,…,NSER-1, does not equal 1, 2 or 3.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The computations are believed to be stable.

8 Parallelism and Performance

G13BHF is not threaded in any implementation.

9 Further Comments

The time taken by G13BHF is approximately proportional to NFV×NPARA.

10 Example

This example follows up that described in G13BGF and makes use of its data. These consist of output series orders and parameter values, input series transfer function orders and the updated state set.
Four new values of the input series are supplied, as are the orders and parameter values for the single input series ARIMA model (which has 2 values of ϕ, 2 values of θ, 1 value of Θ, single seasonal differencing and a seasonal period of 4), and the estimated residual variances for the input series ARIMA model and the output noise ARIMA model.
Four forecast values and their standard errors are computed and printed; also the values of the components zt and the output noise component nt corresponding to the forecasts.

10.1 Program Text

Program Text (g13bhfe.f90)

10.2 Program Data

Program Data (g13bhfe.d)

10.3 Program Results

Program Results (g13bhfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13BJF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13BJF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13BJF produces forecasts of a time series (the output series) which depends on one or more other (input) series via a previously estimated multi-input model for which the state set information is not available. The future values of the input series must be supplied. In contrast with G13BHF the original past values of the input and output series are required. Standard errors of the forecasts are produced. If future values of some of the input series have been obtained as forecasts using ARIMA models for those series, this may be allowed for in the calculation of the standard errors.

2 Specification

SUBROUTINE G13BJF ( MR, NSER, MT, PARA, NPARA, KFC, NEV, NFV, XXY, LDXXY, KZEF, RMSXY, MRX, PARX, LDPARX, FVA, FSD, STTF, ISTTF, NSTTF, WA, IWA, MWA, IMWA, IFAIL)
INTEGER | MR(7), NSER, MT(4,NSER), NPARA, KFC, NEV, NFV, LDXXY, KZEF, MRX(7,NSER), LDPARX, ISTTF, NSTTF, IWA, MWA(IMWA), IMWA, IFAIL
REAL (KIND=nag_wp) | PARA(NPARA), XXY(LDXXY,NSER), RMSXY(NSER), PARX(LDPARX,NSER), FVA(NFV), FSD(NFV), STTF(ISTTF), WA(IWA)

3 Description

G13BJF has two stages. The first stage is essentially the same as a call to the model estimation routine G13BEF, with zero iterations. In particular, all the parameters remain unchanged in the supplied input series transfer function models and output noise series ARIMA model. The internal nuisance parameters associated with the pre-observation period effects of the input series are estimated where requested, and so are any backforecasts of the output noise series. The output components zt and nt, and residuals at are calculated exactly as in Section 3 in G13BEF, and the state set for forecasting is constituted.
The second stage is essentially the same as a call to the forecasting routine G13BHF. The same information is required, and the same information is returned.
Use of G13BJF should be confined to situations in which the state set for forecasting is unknown. Forecasting from the original data is relatively expensive because it requires recalculation of the state set. G13BJF returns the state set for use in producing further forecasts using G13BHF, or for updating the state set using G13BGF.

4 References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day

5 Arguments

1:   MR 7 – INTEGER arrayInput
On entry: the orders vector p,d,q,P,D,Q,s of the ARIMA model for the output noise component.
p, q, P and Q refer respectively to the number of autoregressive ϕ, moving average θ, seasonal autoregressive Φ and seasonal moving average Θ parameters.
d, D and s refer respectively to the order of non-seasonal differencing, the order of seasonal differencing and the seasonal period.
Constraints:
  • p, d, q, P, D, Q, s≥0;
  • p+q+P+Q>0;
  • s≠1;
  • if s=0, P+D+Q=0;
  • if s>1, P+D+Q>0;
  • d+s×P+D≤n;
  • p+d-q+s×P+D-Q≤n.
2:   NSER – INTEGERInput
On entry: the number of input and output series. There may be any number of input series (including none), but only one output series.
3:   MT 4 NSER – INTEGER arrayInput
On entry: the transfer function model orders b, p and q of each of the input series. The data for input series i is held in column i. Row 1 holds the value bi, row 2 holds the value qi and row 3 holds the value pi.
For a simple input, bi=qi=pi=0.
Row 4 holds the value ri, where ri=1 for a simple input, and ri=2​ or ​3 for a transfer function input.
The choice ri=3 leads to estimation of the pre-period input effects as nuisance parameters, and ri=2 suppresses this estimation. This choice may affect the returned forecasts and the state set.
When ri=1, any nonzero contents of rows 1, 2 and 3 of column i are ignored.
Constraint: MT 4 i=1, 2 or 3, for i=1,2,…,NSER-1.
4:   PARA NPARA – REAL (KIND=nag_wp) arrayInput/Output
On entry: estimates of the multi-input model parameters. These are in order, firstly the ARIMA model parameters: p values of ϕ parameters, q values of θ parameters, P values of Φ parameters, Q values of Θ parameters.
These are followed by the transfer function model parameter values ω 0,ω 1,…,ω q 1, δ 1,…,δ p 1 for the first of any input series and similarly for each subsequent input series. The final component of PARA is the value of the constant c.
On exit: the parameter values may be updated using an additional iteration in the estimation process.
5:   NPARA – INTEGERInput
On entry: the exact number of ϕ, θ, Φ, Θ, ω, δ, c parameters, so that NPARA=p+q+P+Q+NSER+∑p+q, the summation being over all the input series. (c must be included whether its value was previously estimated or was set fixed.)
6:   KFC – INTEGERInput
On entry: must be set to 1 if the constant was estimated when the model was fitted, and 0 if it was held at a fixed value. This only affects the degrees of freedom used in calculating the estimated residual variance.
Constraint: KFC=0 or 1.
7:   NEV – INTEGERInput
On entry: the number of original (undifferenced) values in each of the input and output time series.
8:   NFV – INTEGERInput
On entry: the number of forecast values of the output series required.
Constraint: NFV>0.
9:   XXY LDXXYNSER – REAL (KIND=nag_wp) arrayInput/Output
On entry: the columns of XXY must contain in the first NEV places, the past values of each of the input and output series, in that order. In the next NFV places, the columns relating to the input series (i.e., columns 1 to NSER-1) contain the future values of the input series which are necessary for construction of the forecasts of the output series y.
On exit: if KZEF=0 then XXY is unchanged except that the relevant NFV values in the column relating to the output series (column NSER) contain the forecast values (FVA), but if KZEF≠0 then the columns of XXY contain the corresponding values of the input component series zt and the values of the output noise component nt, in that order.
10:   LDXXY – INTEGERInput
On entry: the first dimension of the array XXY as declared in the (sub)program from which G13BJF is called.
Constraint: LDXXY≥NEV+NFV.
11:   KZEF – INTEGERInput
On entry: must be set to 0 if the relevant NFV values of the forecasts (FVA) are to be held in the output series column (NSER) of XXY (which is otherwise unchanged) on exit, and must not be set to 0 if the values of the input component series zt and the values of the output noise component nt are to overwrite the contents of XXY on exit.
12:   RMSXY NSER – REAL (KIND=nag_wp) arrayInput/Output
On entry: the first NSER-1 elements of RMSXY must contain the estimated residual variance of the input series ARIMA models. In the case of those inputs for which no ARIMA model is available or its effects are to be excluded in the calculation of forecast standard errors, the corresponding entry of RMSXY should be set to 0.
On exit: RMSXY NSER contains the estimated residual variance of the output noise ARIMA model which is calculated from the supplied series. Otherwise RMSXY is unchanged.
13:   MRX 7 NSER – INTEGER arrayInput/Output
On entry: the orders array for each of the input series ARIMA models. Thus, column i contains values of p, d, q, P, D, Q, s for input series i. In the case of those inputs for which no ARIMA model is available, the corresponding orders should be set to 0.
On exit: unchanged, except for column NSER which is used as workspace.
14:   PARX LDPARXNSER – REAL (KIND=nag_wp) arrayInput
On entry: values of the parameters (ϕ, θ, Φ, and Θ) for each of the input series ARIMA models.
Thus column i contains MRX 1 i values of ϕ, MRX 3 i values of θ, MRX 4 i values of Φ and MRX 6 i values of Θ, in that order.
Values in the columns relating to those input series for which no ARIMA model is available are ignored.
15:   LDPARX – INTEGERInput
On entry: the first dimension of the array PARX as declared in the (sub)program from which G13BJF is called.
Constraint: LDPARX≥nce, where nce is the maximum number of parameters in any of the input series ARIMA models. If there are no input series, then LDPARX≥1.
16:   FVA NFV – REAL (KIND=nag_wp) arrayOutput
On exit: the required forecast values for the output series. (Note that these are also output in column NSER of XXY if KZEF=0.)
17:   FSD NFV – REAL (KIND=nag_wp) arrayOutput
On exit: the standard errors for each of the forecast values.
18:   STTF ISTTF – REAL (KIND=nag_wp) arrayOutput
On exit: the NSTTF values of the state set based on the first NEV sets of (past) values of the input and output series.
19:   ISTTF – INTEGERInput
On entry: the dimension of the array STTF as declared in the (sub)program from which G13BJF is called.
Constraint: ISTTF≥P×s+d+D×s+q+max p,Q×s+ncf, where ncf=∑bi+qi+pi and the summation is over all input series for which ri>1.
20:   NSTTF – INTEGEROutput
On exit: the number of values in the state set array STTF.
21:   WA IWA – REAL (KIND=nag_wp) arrayWorkspace
22:   IWA – INTEGERInput
On entry: the dimension of the array WA as declared in the (sub)program from which G13BJF is called.
It is not practical to outline a method for deriving the exact minimum permissible value of IWA, but the following gives a reasonably good approximation which tends to be on the conservative side.
Note: there are three error indicators associated with IWA. These are IFAIL=4, 5 or 6. The first of these probably indicates an abnormal entry value of NFV, while the second indicates that IWA is much too small and needs to be increased by a substantial amount. The last of these indicates that IWA is too small but returns the necessary minimum value in MWA 1.
Let q′=q+Q×s and d′=d+D×s, where the output noise ARIMA model orders are p, d, q, P, D, Q, s.
Let there be l input series, where l=NSER-1.
Let | m xi=max bi+qi,pi, | if ri=3, for i=1,2,…,l, if l>0
m xi=0, | if ri≠3, for i=1,2,…,l, if l>0
where the transfer function model orders of input series i are given by bi, qi, pi, ri.
Let qx=max q′,m x 1,m x 2,…,m xl
Let ncg=NPARA+qx+∑i=1 l m xi and nch=N+d+6×qx.
Finally, let nci=NSER, and then increment nci by 1 every time any of the following conditions are satisfied. (The last two conditions should be applied separately to each input series, so that for example if we have two input series and p 1>0 and p 2>0, then nci is incremented by 2 in respect of these.)
The conditions are:
  • p>0
  • q>0
  • P>0
  • Q>0
  • qx>0
  • m xi>0, separately, for i=1,2,…,l, if l>0
  • pi>0, separately, for i=1,2,…,l, if l>0,
then IWA>2× ncg 2+nch×nci+4.
23:   MWA IMWA – INTEGER arrayWorkspace
24:   IMWA – INTEGERInput
On entry: the dimension of the array MWA as declared in the (sub)program from which G13BJF is called.
Constraint: IMWA≥16×NSER+7×ncg+3×NPARA+27.
The derivation of ncg is described under IWA.
When IMWA is too small, as indicated by IFAIL=7, the requisite minimum value of IMWA is returned in MWA 1.
25:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | KFC<0,
or | KFC>1,
or | LDXXY<NEV+NFV,
or | NFV≤0.
IFAIL=2
On entry, LDPARX is too small or NPARA is inconsistent with the orders specified in arrays MR and MT; or one of the ri, stored in MT 4 i, does not equal 1, 2 or 3.
IFAIL=3
On entry or during execution, one or more sets of δ parameters do not satisfy the stationarity or invertibility test conditions.
IFAIL=4
On entry, IWA is too small for the final forecasting calculations. This is a highly unlikely error, and would probably indicate that NFV was abnormally large.
IFAIL=5
On entry, IWA is too small by a very considerable margin. No information is supplied about the requisite minimum size.
IFAIL=6
On entry, IWA is too small, but the requisite minimum size is returned in MWA 1.
IFAIL=7
On entry, IMWA is too small, but the requisite minimum size is returned in MWA 1.
IFAIL=8
Unable to calculate the latest parameter estimates.
IFAIL=9
This indicates a failure in the inversion of the second derivative matrix associated with parameter estimation.
IFAIL=10
On entry or during execution, one or more sets of the ARIMA (ϕ, θ, Φ or Θ) parameters do not satisfy the stationarity or invertibility test conditions.
IFAIL=11
On entry, ISTTF is too small.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The computations are believed to be stable.

8 Parallelism and Performance

G13BJF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13BJF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

The time taken by G13BJF is approximately proportional to the product of the length of each series and the square of the number of parameters in the multi-input model.

10 Example

The data in this example relates to 40 observations of an output time series and 5 input time series. The output series has one autoregressive ϕ parameter and one seasonal moving average Θ parameter, with initial values ϕ=0.495, Θ=0.238 and c=-82.858. The seasonal period is 4. This example differs from the example in G13BEF in that four of the input series are simple series and the fifth is defined by a transfer function with orders b 5=1, q 5=0, p 5=1, r 5=3, which allows for pre-observation period effects. The initial values for the transfer model are:
  • ω 1=-0.367,   ω 2=-3.876,   ω 3=4.516,   ω 4=2.474 ω 5=8.629,  δ 1=0.688.
A further 8 values of the input series are supplied, and it is assumed that the values for the fifth series have themselves been forecast from an ARIMA model with orders 2 0 2 0 1 1 4 , in which ϕ 1=1.6743, ϕ 2=-0.9505, θ 1=1.4605, θ 2=-0.4862 and Θ 1=0.8993, and for which the residual mean square is 0.1720.
The following are computed and printed out: the state set after initial processing of the original 40 sets of values, the estimated residual variance for the output noise series, the 8 forecast values and their standard errors, and the values of the components zt and the output noise component nt.

10.1 Program Text

Program Text (g13bjfe.f90)

10.2 Program Data

Program Data (g13bjfe.d)

10.3 Program Results

Program Results (g13bjfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13CAF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13CAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13CAF calculates the smoothed sample spectrum of a univariate time series using one of four lag windows – rectangular, Bartlett, Tukey or Parzen window.

2 Specification

SUBROUTINE G13CAF ( NX, MTX, PX, IW, MW, IC, NC, C, KC, L, LG, NXG, XG, NG, STATS, IFAIL)
INTEGER | NX, MTX, IW, MW, IC, NC, KC, L, LG, NXG, NG, IFAIL
REAL (KIND=nag_wp) | PX, C(NC), XG(NXG), STATS(4)

3 Description

The smoothed sample spectrum is defined as
f^ω=1 2 π C 0+2∑k=1 M-1 wkCk cos ωk ,
where M is the window width, and is calculated for frequency values
ωi=2 πi L,  i=0,1,…,L/2,
where denotes the integer part.
The autocovariances Ck may be supplied by you, or constructed from a time series x 1,x 2,…,xn, as
Ck=1 n∑t=1 n-k xtx t+k,
the fast Fourier transform (FFT) being used to carry out the convolution in this formula.
The time series may be mean or trend corrected (by classical least squares), and tapered before calculation of the covariances, the tapering factors being those of the split cosine bell:
12 1-cos π t-12/T, 1≤t≤T 12 1-cos π n-t+12/T, n+ 1-T≤t≤n 1, otherwise,
where T= np 2 and p is the tapering proportion.
The smoothing window is defined by
wk=W kM ,  k≤M-1,
which for the various windows is defined over 0≤α<1 by
rectangular:
W α=1
Bartlett:
W α = 1-α
Tukey:
W α=12 1+cos πα
Parzen:
W α= 1- 6 α 2+ 6 α 3, 0≤α≤12 W α= 2 1-α 3, 12<α< 1.
The sampling distribution of f^ω is approximately that of a scaled χd 2 variate, whose degrees of freedom d is provided by the routine, together with multiplying limits mu, ml from which approximate 95% confidence intervals for the true spectrum f ω may be constructed as ml × f ^ ω , mu × f ^ ω . Alternatively, log f^ω may be returned, with additive limits.
The bandwidth b of the corresponding smoothing window in the frequency domain is also provided. Spectrum estimates separated by (angular) frequencies much greater than b may be assumed to be independent.

4 References

Bloomfield P (1976) Fourier Analysis of Time Series: An Introduction Wiley
Jenkins G M and Watts D G (1968) Spectral Analysis and its Applications Holden–Day

5 Arguments

1:   NX – INTEGERInput
On entry: n, the length of the time series.
Constraint: NX≥1.
2:   MTX – INTEGERInput
On entry: if covariances are to be calculated by the routine (IC=0), MTX must specify whether the data are to be initially mean or trend corrected.
MTX=0
For no correction.
MTX=1
For mean correction.
MTX=2
For trend correction.
Constraint: if IC=0, 0≤MTX≤2
If covariances are supplied (IC≠0), MTX is not used.
3:   PX – REAL (KIND=nag_wp)Input
On entry: if covariances are to be calculated by the routine (IC=0), PX must specify the proportion of the data (totalled over both ends) to be initially tapered by the split cosine bell taper.
If covariances are supplied IC≠0, PX must specify the proportion of data tapered before the supplied covariances were calculated and after any mean or trend correction. PX is required for the calculation of output statistics. A value of 0.0 implies no tapering.
Constraint: 0.0≤PX≤1.0.
4:   IW – INTEGERInput
On entry: the choice of lag window.
IW=1
Rectangular.
IW=2
Bartlett.
IW=3
Tukey.
IW=4
Parzen.
Constraint: 1≤IW≤4.
5:   MW – INTEGERInput
On entry: M, the ‘cut-off’ point of the lag window. Windowed covariances at lag M or greater are zero.
Constraint: 1≤MW≤NX.
6:   IC – INTEGERInput
On entry: indicates whether covariances are to be calculated in the routine or supplied in the call to the routine.
IC=0
Covariances are to be calculated.
IC≠0
Covariances are to be supplied.
7:   NC – INTEGERInput
On entry: the number of covariances to be calculated in the routine or supplied in the call to the routine.
Constraint: MW≤NC≤NX.
8:   C NC – REAL (KIND=nag_wp) arrayInput/Output
On entry: if IC≠0, C must contain the NC covariances for lags from 0 to NC-1, otherwise C need not be set.
On exit: if IC=0, C will contain the NC calculated covariances.
If IC≠0, the contents of C will be unchanged.
9:   KC – INTEGERInput
On entry: if IC=0, KC must specify the order of the fast Fourier transform (FFT) used to calculate the covariances.
If IC≠0, that is covariances are supplied, KC is not used.
Constraint: KC≥NX+NC.
10:   L – INTEGERInput
On entry: L, the frequency division of the spectral estimates as 2 π L . Therefore it is also the order of the FFT used to construct the sample spectrum from the covariances.
Constraint: L≥2×MW-1.
11:   LG – INTEGERInput
On entry: indicates whether unlogged or logged spectral estimates and confidence limits are required.
LG=0
Unlogged.
LG≠0
Logged.
12:   NXG – INTEGERInput
On entry: the dimension of the array XG as declared in the (sub)program from which G13CAF is called.
Constraints:
  • if IC=0, NXG≥max KC,L;
  • if IC≠0, NXG≥L.
13:   XG NXG – REAL (KIND=nag_wp) arrayInput/Output
On entry: if the covariances are to be calculated, then XG must contain the NX data points. If covariances are supplied, XG may contain any values.
On exit: contains the NG spectral estimates, f^ωi, for i=0,1,…,L/2 in XG 1 to XG NG respectively (logged if LG=1). The elements XG i, for i=NG+1,…,NXG contain 0.0.
14:   NG – INTEGEROutput
On exit: the number of spectral estimates, L/2+1, in XG.
15:   STATS 4 – REAL (KIND=nag_wp) arrayOutput
On exit: four associated statistics. These are the degrees of freedom in STATS 1, the lower and upper 95% confidence limit factors in STATS 2 and STATS 3 respectively (logged if LG=1), and the bandwidth in STATS 4.
16:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, IC=0 and MTX<0: MTX=value.
On entry, IC=0 and MTX>2: MTX=value.
On entry, IW=value.
Constraint: IW=1, 2, 3 or 4.
On entry, MW=value.
Constraint: MW≥1.
On entry, MW=value and NX=value.
Constraint: MW≤NX.
On entry, NC=value and MW=value.
Constraint: NC≥MW.
On entry, NC=value and NX=value.
Constraint: NC≤NX.
On entry, NX=value.
Constraint: NX≥1.
On entry, NXG=value, KC=value and L=value.
Constraint: if IC=0, NXG≥max KC,L.
On entry, NXG=value and L=value.
Constraint: if IC≠0, NXG≥L.
On entry, PX=value.
Constraint: PX≥0.0.
On entry, PX=value.
Constraint: PX≤1.0.
IFAIL=2
On entry, KC=value, NX=value and NC=value.
Constraint: if IC=0, KC≥NX+NC.
IFAIL=3
On entry, L=value and MW=value.
Constraint: L≥2×MW-1.
IFAIL=4
One or more spectral estimates are negative.
Unlogged spectral estimates are returned in XG, and the degrees of freedom, unloged confidence limit factors and bandwidth in STATS.
IFAIL=5
The calculation of confidence limit factors has failed.
Spectral estimates (logged if requested) are returned in XG, and degrees of freedom and bandwidth in STATS.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The FFT is a numerically stable process, and any errors introduced during the computation will normally be insignificant compared with uncertainty in the data.

8 Parallelism and Performance

G13CAF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13CAF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

G13CAF carries out two FFTs of length KC to calculate the covariances and one FFT of length L to calculate the sample spectrum. The time taken by the routine for an FFT of length n is approximately proportional to n log n (but see Section 9 in C06PAF for further details).

10 Example

This example reads a time series of length 256. It selects the mean correction option, a tapering proportion of 0.1, the Parzen smoothing window and a cut-off point for the window at lag 100. It chooses to have 100 auto-covariances calculated and unlogged spectral estimates at a frequency division of 2 π/200. It then calls G13CAF to calculate the univariate spectrum and statistics and prints the autocovariances and the spectrum together with its 95% confidence multiplying limits.

10.1 Program Text

Program Text (g13cafe.f90)

10.2 Program Data

Program Data (g13cafe.d)

10.3 Program Results

Program Results (g13cafe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13CBF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13CBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13CBF calculates the smoothed sample spectrum of a univariate time series using spectral smoothing by the trapezium frequency (Daniell) window.

2 Specification

SUBROUTINE G13CBF ( NX, MTX, PX, MW, PW, L, KC, LG, XG, NG, STATS, IFAIL)
INTEGER | NX, MTX, MW, L, KC, LG, NG, IFAIL
REAL (KIND=nag_wp) | PX, PW, XG(KC), STATS(4)

3 Description

The supplied time series may be mean or trend corrected (by least squares), and tapered, the tapering factors being those of the split cosine bell:
12 1-cos π t-12 /T , 1≤t≤T 12 1-cos π n-t+12 /T , n+1-T≤t≤n 1, otherwise,
where T= np 2 and p is the tapering proportion.
The unsmoothed sample spectrum
f*ω=1 2 π ∑t=1 n xt exp iω t 2
is then calculated for frequency values
ωk=2 π k K,   k= 0,1,…,K/2,
where [ ] denotes the integer part.
The smoothed spectrum is returned as a subset of these frequencies for which k is a multiple of a chosen value r, i.e.,
ω rl=νl=2 πl L,  l=0,1,…,L/2,
where K=r×L. You will normally fix L first, then choose r so that K is sufficiently large to provide an adequate representation for the unsmoothed spectrum, i.e., K≥2×n. It is possible to take L=K, i.e., r=1.
The smoothing is defined by a trapezium window whose shape is supplied by the function
W α=1, α≤p W α=1-α 1-p , p<α≤1
the proportion p being supplied by you.
The width of the window is fixed as 2 π/M by you supplying M. A set of averaging weights are constructed:
Wk=g×W ωk M π ,  0≤ωk≤πM,
where g is a normalizing constant, and the smoothed spectrum obtained is
f^νl=∑ωk< πMWk f*νl+ωk.
If no smoothing is required M should be set to n, in which case the values returned are f^νl=f*νl. Otherwise, in order that the smoothing approximates well to an integration, it is essential that K≫M, and preferable, but not essential, that K be a multiple of M. A choice of L>M would normally be required to supply an adequate description of the smoothed spectrum. Typical choices of L≃n and K≃4 n should be adequate for usual smoothing situations when M<n/5.
The sampling distribution of f^ω is approximately that of a scaled χd 2 variate, whose degrees of freedom d is provided by the routine, together with multiplying limits mu, ml from which approximate 95% confidence intervals for the true spectrum f ω may be constructed as ml × f ^ ω mu × f ^ ω . Alternatively, log f^ω may be returned, with additive limits.
The bandwidth b of the corresponding smoothing window in the frequency domain is also provided. Spectrum estimates separated by (angular) frequencies much greater than b may be assumed to be independent.

4 References

Bloomfield P (1976) Fourier Analysis of Time Series: An Introduction Wiley
Jenkins G M and Watts D G (1968) Spectral Analysis and its Applications Holden–Day

5 Arguments

1:   NX – INTEGERInput
On entry: n, the length of the time series.
Constraint: NX≥1.
2:   MTX – INTEGERInput
On entry: whether the data are to be initially mean or trend corrected.
MTX=0
For no correction.
MTX=1
For mean correction.
MTX=2
For trend correction.
Constraint: 0≤MTX≤2.
3:   PX – REAL (KIND=nag_wp)Input
On entry: the proportion of the data (totalled over both ends) to be initially tapered by the split cosine bell taper. (A value of 0.0 implies no tapering.)
Constraint: 0.0≤PX≤1.0.
4:   MW – INTEGERInput
On entry: the value of M which determines the frequency width of the smoothing window as 2 π/M. A value of n implies no smoothing is to be carried out.
Constraint: 1≤MW≤NX.
5:   PW – REAL (KIND=nag_wp)Input
On entry: p, the shape parameter of the trapezium frequency window.
A value of 0.0 gives a triangular window, and a value of 1.0 a rectangular window.
If MW=NX (i.e., no smoothing is carried out), PW is not used.
Constraint: 0.0≤PW≤1.0.
6:   L – INTEGERInput
On entry: L, the frequency division of smoothed spectral estimates as 2 π/L.
Constraints:
  • L≥1;
  • L must be a factor of KC.
7:   KC – INTEGERInput
On entry: K, the order of the fast Fourier transform (FFT) used to calculate the spectral estimates.
Constraints:
  • KC≥2×NX;
  • KC must be a multiple of L.
8:   LG – INTEGERInput
On entry: indicates whether unlogged or logged spectral estimates and confidence limits are required.
LG=0
For unlogged.
LG≠0
For logged.
9:   XG KC – REAL (KIND=nag_wp) arrayInput/Output
On entry: the n data points.
On exit: contains the NG spectral estimates f^ωi, for i=0,1,…,L/2, in XG 1 to XG NG (logged if LG≠0). The elements XG i, for i=NG+1,…,KC, contain 0.0.
10:   NG – INTEGEROutput
On exit: the number of spectral estimates, L/2+1, in XG.
11:   STATS 4 – REAL (KIND=nag_wp) arrayOutput
On exit: four associated statistics. These are the degrees of freedom in STATS 1, the lower and upper 95% confidence limit factors in STATS 2 and STATS 3 respectively (logged if LG≠0), and the bandwidth in STATS 4.
12:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if IFAIL≠0 on exit, the recommended value is -1. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Note: G13CBF may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the routine:
IFAIL=1
On entry, L=value.
Constraint: L≥1.
On entry, MTX=value.
Constraint: MTX≤2.
On entry, MTX=value.
Constraint: MTX≥0.
On entry, MW=value.
Constraint: MW≥1.
On entry, MW=value and NX=value.
Constraint: MW≤NX.
On entry, NX=value.
Constraint: NX≥1.
On entry, PX=value, MW=value and NX=value.
Constraint: if PW<0.0, MW=NX.
On entry, PX=value, MW=value and NX=value.
Constraint: if PW>1.0, MW=NX.
On entry, PX=value.
Constraint: PX≥0.0.
On entry, PX=value.
Constraint: PX≤1.0.
IFAIL=2
On entry, KC=value and L=value.
Constraint: KC must be a multiple of L.
On entry, KC=value and NX=value.
Constraint: KC≥2×NX.
IFAIL=4
One or more spectral estimates are negative.
Unlogged spectral estimates are returned in XG, and the degrees of freedom, unloged confidence limit factors and bandwidth in STATS.
IFAIL=5
The calculation of confidence limit factors has failed.
Spectral estimates (logged if requested) are returned in XG, and degrees of freedom and bandwidth in STATS.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The FFT is a numerically stable process, and any errors introduced during the computation will normally be insignificant compared with uncertainty in the data.

8 Parallelism and Performance

G13CBF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13CBF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

G13CBF carries out a FFT of length KC to calculate the sample spectrum. The time taken by the routine for this is approximately proportional to KC×log KC (but see Section 9 in C06PAF for further details).

10 Example

This example reads a time series of length 131. It then calls G13CBF to calculate the univariate spectrum and prints the logged spectrum together with 95% confidence limits.

10.1 Program Text

Program Text (g13cbfe.f90)

10.2 Program Data

Program Data (g13cbfe.d)

10.3 Program Results

Program Results (g13cbfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13CCF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13CCF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13CCF calculates the smoothed sample cross spectrum of a bivariate time series using one of four lag windows: rectangular, Bartlett, Tukey or Parzen.

2 Specification

SUBROUTINE G13CCF ( NXY, MTXY, PXY, IW, MW, ISH, IC, NC, CXY, CYX, KC, L, NXYG, XG, YG, NG, IFAIL)
INTEGER | NXY, MTXY, IW, MW, ISH, IC, NC, KC, L, NXYG, NG, IFAIL
REAL (KIND=nag_wp) | PXY, CXY(NC), CYX(NC), XG(NXYG), YG(NXYG)

3 Description

The smoothed sample cross spectrum is a complex valued function of frequency ω, f xy ω=cf ω+iqf ω, defined by its real part or co-spectrum
cf ω=1 2 π ∑k=-M+1 M-1 wkC xy k+S cos ωk
and imaginary part or quadrature spectrum
qf ω=1 2 π ∑k=-M+ 1 M- 1 wkC xy k+S sin ω k
where wk=w-k, for k=0,1,…,M-1, is the smoothing lag window as defined in the description of G13CAF. The alignment shift S is recommended to be chosen as the lag k at which the cross-covariances c xy k peak, so as to minimize bias.
The results are calculated for frequency values
ωj=2 πj L,  j=0,1,…,L/2,
where denotes the integer part.
The cross-covariances c xy k may be supplied by you, or constructed from supplied series x 1,x 2,…,xn; y 1,y 2,…,yn as
c xy k=∑t=1 n-k xty t+k n,  k≥0
c xy k=∑t= 1-k n xty t+k n=c yx-k,   k< 0
this convolution being carried out using the finite Fourier transform.
The supplied series may be mean and trend corrected and tapered before calculation of the cross-covariances, in exactly the manner described in G13CAF for univariate spectrum estimation. The results are corrected for any bias due to tapering.
The bandwidth associated with the estimates is not returned. It will normally already have been calculated in previous calls of G13CAF for estimating the univariate spectra of yt and xt.

4 References

Bloomfield P (1976) Fourier Analysis of Time Series: An Introduction Wiley
Jenkins G M and Watts D G (1968) Spectral Analysis and its Applications Holden–Day

5 Arguments

1:   NXY – INTEGERInput
On entry: n, the length of the time series x and y.
Constraint: NXY≥1.
2:   MTXY – INTEGERInput
On entry: if cross-covariances are to be calculated by the routine (IC=0), MTXY must specify whether the data is to be initially mean or trend corrected.
MTXY=0
For no correction.
MTXY=1
For mean correction.
MTXY=2
For trend correction.
If cross-covariances are supplied IC≠0, MTXY is not used.
Constraint: if IC=0, MTXY=0, 1 or 2.
3:   PXY – REAL (KIND=nag_wp)Input
On entry: if cross-covariances are to be calculated by the routine (IC=0), PXY must specify the proportion of the data (totalled over both ends) to be initially tapered by the split cosine bell taper. A value of 0.0 implies no tapering.
If cross-covariances are supplied IC≠0, PXY is not used.
Constraint: if IC=0, 0.0≤PXY≤1.0.
4:   IW – INTEGERInput
On entry: the choice of lag window.
IW=1
Rectangular.
IW=2
Bartlett.
IW=3
Tukey.
IW=4
Parzen.
Constraint: 1≤IW≤4.
5:   MW – INTEGERInput
On entry: M, the ‘cut-off’ point of the lag window, relative to any alignment shift that has been applied. Windowed cross-covariances at lags -MW+ISH or less, and at lags MW+ISH or greater are zero.
Constraints:
  • MW≥1;
  • MW+ISH≤NXY.
6:   ISH – INTEGERInput
On entry: S, the alignment shift between the x and y series. If x leads y, the shift is positive.
Constraint: -MW<ISH<MW.
7:   IC – INTEGERInput
On entry: indicates whether cross-covariances are to be calculated in the routine or supplied in the call to the routine.
IC=0
Cross-covariances are to be calculated.
IC≠0
Cross-covariances are to be supplied.
8:   NC – INTEGERInput
On entry: the number of cross-covariances to be calculated in the routine or supplied in the call to the routine.
Constraint: MW+ISH≤NC≤NXY.
9:   CXY NC – REAL (KIND=nag_wp) arrayInput/Output
On entry: if IC≠0, CXY must contain the NC cross-covariances between values in the y series and earlier values in time in the x series, for lags from 0 to NC-1.
If IC=0, CXY need not be set.
On exit: if IC=0, CXY will contain the NC calculated cross-covariances.
If IC≠0, the contents of CXY will be unchanged.
10:   CYX NC – REAL (KIND=nag_wp) arrayInput/Output
On entry: if IC≠0, CYX must contain the NC cross-covariances between values in the y series and later values in time in the x series, for lags from 0 to NC-1.
If IC=0, CYX need not be set.
On exit: if IC=0, CYX will contain the NC calculated cross-covariances.
If IC≠0, the contents of CYX will be unchanged.
11:   KC – INTEGERInput
On entry: if IC=0, KC must specify the order of the fast Fourier transform (FFT) used to calculate the cross-covariances.
If IC≠0, that is if covariances are supplied, KC is not used.
Constraint: KC≥NXY+NC.
12:   L – INTEGERInput
On entry: L, the frequency division of the spectral estimates as 2 π L . Therefore it is also the order of the FFT used to construct the sample spectrum from the cross-covariances.
Constraint: L≥2×MW-1.
13:   NXYG – INTEGERInput
On entry: the dimension of the arrays XG and YG as declared in the (sub)program from which G13CCF is called.
Constraints:
  • if IC=0, NXYG≥max KC,L;
  • otherwise NXYG≥L.
14:   XG NXYG – REAL (KIND=nag_wp) arrayInput/Output
On entry: if the cross-covariances are to be calculated, then XG must contain the NXY data points of the x series. If covariances are supplied, XG need not be set.
On exit: contains the real parts of the NG complex spectral estimates in elements XG 1 to XG NG, and XG NG+1 to XG NXYG contain 0.0. The y series leads the x series.
15:   YG NXYG – REAL (KIND=nag_wp) arrayInput/Output
On entry: if cross-covariances are to be calculated, YG must contain the NXY data points of the y series. If covariances are supplied, YG need not be set.
On exit: contains the imaginary parts of the NG complex spectral estimates in elements YG 1 to YG NG, and YG NG+1 to YG NXYG contain 0.0. The y series leads the x series.
16:   NG – INTEGEROutput
On exit: the number, L/2+1, of complex spectral estimates, whose separate parts are held in XG and YG.
17:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, IC=value, NXYG=value and L=value.
Constraint: if IC≠0, NXYG≥L.
On entry, ISH=value and MW=value.
Constraint: ISH≤MW.
On entry, IW=value.
Constraint: IW=1, 2, 3 or 4.
On entry, MTXY=value.
Constraint: if IC=0 then MTXY≠0, 1 or 2.
On entry, MW=value, ISH=value and NXY=value.
Constraint: MW+ISH≤NXY.
On entry, MW=value.
Constraint: MW≥1.
On entry, NC=value, MW=value and ISH=value.
Constraint: NC≥MW+ISH.
On entry, NC=value and NXY=value.
Constraint: NC≤NXY.
On entry, NXY=value.
Constraint: NXY≥1.
On entry, NXYG=value, KC=value and L=value.
Constraint: if IC=0, NXYG≥max KC,L.
On entry, PXY=value.
Constraint: if IC=0, PXY≥0.0.
On entry, PXY=value.
Constraint: if IC=0, PXY≤1.0.
IFAIL=2
On entry, KC=value, NXY=value and NC=value.
Constraint: if IC=0, KC≥NXY+NC.
IFAIL=3
On entry, L=value and MW=value.
Constraint: L≥2×MW-1.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The FFT is a numerically stable process, and any errors introduced during the computation will normally be insignificant compared with uncertainty in the data.

8 Parallelism and Performance

G13CCF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13CCF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

G13CCF carries out two FFTs of length KC to calculate the sample cross-covariances and one FFT of length L to calculate the sample spectrum. The timing of G13CCF is therefore dependent on the choice of these values. The time taken for an FFT of length n is approximately proportional to n log n (but see Section 9 in C06PAF for further details).

10 Example

This example reads two time series of length 296. It then selects mean correction, a 10% tapering proportion, the Parzen smoothing window and a cut-off point of 35 for the lag window. The alignment shift is set to 3 and 50 cross-covariances are chosen to be calculated. The program then calls G13CCF to calculate the cross spectrum and then prints the cross-covariances and cross spectrum.

10.1 Program Text

Program Text (g13ccfe.f90)

10.2 Program Data

Program Data (g13ccfe.d)

10.3 Program Results

Program Results (g13ccfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13CDF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13CDF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13CDF calculates the smoothed sample cross spectrum of a bivariate time series using spectral smoothing by the trapezium frequency (Daniell) window.

2 Specification

SUBROUTINE G13CDF ( NXY, MTXY, PXY, MW, ISH, PW, L, KC, XG, YG, NG, IFAIL)
INTEGER | NXY, MTXY, MW, ISH, L, KC, NG, IFAIL
REAL (KIND=nag_wp) | PXY, PW, XG(KC), YG(KC)

3 Description

The supplied time series may be mean and trend corrected and tapered as in the description of G13CBF before calculation of the unsmoothed sample cross-spectrum
f xy* ω = 1 2 πn ∑ t=1 n yt exp iωt × ∑ t=1 n xt exp-iωt
for frequency values ωj=2 πj K , 0≤ωj≤π.
A correction is made for bias due to any tapering.
As in the description of G13CBF for univariate frequency window smoothing, the smoothed spectrum is returned as a subset of these frequencies,
νl=2 π l L,  l=0,1,…,L/2
where [ ] denotes the integer part.
Its real part or co-spectrum cf νl, and imaginary part or quadrature spectrum qf νl are defined by
f xy νl = cf νl + iqf νl = ∑ ωk < πM w~k f xy* νl+ωk
where the weights w~k are similar to the weights wk defined for G13CBF, but allow for an implicit alignment shift S between the series:
w~k=wk exp-2 π iSk/L.
It is recommended that S is chosen as the lag k at which the cross-covariances c xy k peak, so as to minimize bias.
If no smoothing is required, the integer M, which determines the frequency window width 2 π M , should be set to n.
The bandwidth of the estimates will normally have been calculated in a previous call of G13CBF for estimating the univariate spectra of yt and xt.

4 References

Bloomfield P (1976) Fourier Analysis of Time Series: An Introduction Wiley
Jenkins G M and Watts D G (1968) Spectral Analysis and its Applications Holden–Day

5 Arguments

1:   NXY – INTEGERInput
On entry: n, the length of the time series x and y.
Constraint: NXY≥1.
2:   MTXY – INTEGERInput
On entry: whether the data is to be initially mean or trend corrected.
MTXY=0
For no correction.
MTXY=1
For mean correction.
MTXY=2
For trend correction.
Constraint: 0≤MTXY≤2.
3:   PXY – REAL (KIND=nag_wp)Input
On entry: the proportion of the data (totalled over both ends) to be initially tapered by the split cosine bell taper.
A value of 0.0 implies no tapering.
Constraint: 0.0≤PXY≤1.0.
4:   MW – INTEGERInput
On entry: M, the frequency width of the smoothing window as 2 π M .
A value of n implies that no smoothing is to be carried out.
Constraint: 1≤MW≤NXY.
5:   ISH – INTEGERInput
On entry: S, the alignment shift between the x and y series. If x leads y, the shift is positive.
Constraint: -L<ISH<L.
6:   PW – REAL (KIND=nag_wp)Input
On entry: p, the shape parameter of the trapezium frequency window.
A value of 0.0 gives a triangular window, and a value of 1.0 a rectangular window.
If MW=NXY (i.e., no smoothing is carried out) then PW is not used.
Constraint: if MW≠NXY, 0.0≤PW≤1.0.
7:   L – INTEGERInput
On entry: L, the frequency division of smoothed cross spectral estimates as 2 π L .
Constraints:
  • L≥1;
  • L must be a factor of KC.
8:   KC – INTEGERInput
On entry: the dimension of the arrays XG and YG as declared in the (sub)program from which G13CDF is called. The order of the fast Fourier transform ( FFT) used to calculate the spectral estimates.
Constraints:
  • KC≥2×NXY;
  • KC must be a multiple of L.
9:   XG KC – REAL (KIND=nag_wp) arrayInput/Output
On entry: the NXY data points of the x series.
On exit: the real parts of the NG cross spectral estimates in elements XG 1 to XG NG, and XG NG+1 to XG KC contain 0.0. The y series leads the x series.
10:   YG KC – REAL (KIND=nag_wp) arrayInput/Output
On entry: the NXY data points of the y series.
On exit: the imaginary parts of the NG cross spectral estimates in elements YG 1 to YG NG, and YG NG+1 to YG KC contain 0.0. The y series leads the x series.
11:   NG – INTEGEROutput
On exit: the number of spectral estimates, L/2+1, whose separate parts are held in XG and YG.
12:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, ISH=value and L=value.
Constraint: ISH<L.
On entry, L=value.
Constraint: L≥1.
On entry, MTXY=value.
Constraint: MTXY≤2.
On entry, MTXY=value.
Constraint: MTXY≥0.
On entry, MW=value.
Constraint: MW≥1.
On entry, MW=value and NXY=value.
Constraint: MW≤NXY.
On entry, NXY=value.
Constraint: NXY≥1.
On entry, PXY=value, MW=value and NXY=value.
Constraint: if PW<0.0, MW=NXY.
On entry, PXY=value, MW=value and NXY=value.
Constraint: if PW>1.0, MW=NXY.
On entry, PXY=value.
Constraint: PXY≥0.0.
On entry, PXY=value.
Constraint: PXY≤1.0.
IFAIL=2
On entry, KC=value and L=value.
Constraint: KC must be a multiple of L.
On entry, KC=value and NXY=value.
Constraint: KC≥2×NXY.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The FFT is a numerically stable process, and any errors introduced during the computation will normally be insignificant compared with uncertainty in the data.

8 Parallelism and Performance

G13CDF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13CDF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

G13CDF carries out an FFT of length KC to calculate the sample cross spectrum. The time taken by the routine for this is approximately proportional to KC×log KC (but see routine document C06PAF for further details).

10 Example

This example reads two time series of length 296. It selects mean correction and a 10% tapering proportion. It selects a 2 π/16 frequency width of smoothing window, a window shape parameter of 0.5 and an alignment shift of 3. It then calls G13CDF to calculate the smoothed sample cross spectrum and prints the results.

10.1 Program Text

Program Text (g13cdfe.f90)

10.2 Program Data

Program Data (g13cdfe.d)

10.3 Program Results

Program Results (g13cdfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13CEF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13CEF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

For a bivariate time series, G13CEF calculates the cross amplitude spectrum and squared coherency, together with lower and upper bounds from the univariate and bivariate (cross) spectra.

2 Specification

SUBROUTINE G13CEF ( XG, YG, XYRG, XYIG, NG, STATS, CA, CALW, CAUP, T, SC, SCLW, SCUP, IFAIL)
INTEGER | NG, IFAIL
REAL (KIND=nag_wp) | XG(NG), YG(NG), XYRG(NG), XYIG(NG), STATS(4), CA(NG), CALW(NG), CAUP(NG), T, SC(NG), SCLW(NG), SCUP(NG)

3 Description

Estimates of the cross amplitude spectrum A ω and squared coherency W ω are calculated for each frequency ω as
A ω=f xy ω=cf ω 2+qf ω 2  and W ω= f xy ω 2 f xx ω f yy ω ,
where
  • cf ω and qf ω are the co-spectrum and quadrature spectrum estimates between the series, i.e., the real and imaginary parts of the cross spectrum f xy ω as obtained using G13CCF or G13CDF;
  • f xx ω and f yy ω are the univariate spectrum estimates for the two series as obtained using G13CAF or G13CBF.
The same type and amount of smoothing should be used for these estimates, and this is specified by the degrees of freedom and bandwidth values which are passed from the calls of G13CAF or G13CBF.
Upper and lower 95% confidence limits for the cross amplitude are given approximately by
A ω 1±1.96/d W ω-1+1 ,
except that a negative lower limit is reset to 0.0, in which case the approximation is rather poor. You are therefore particularly recommended to compare the coherency estimate W ω with the critical value T derived from the upper 5% point of the F-distribution on 2,d-2 degrees of freedom:
T=2 F d-2+2 F ,
where d is the degrees of freedom associated with the univariate spectrum estimates. The value of T is returned by the routine.
The hypothesis that the series are unrelated at frequency ω, i.e., that both the true cross amplitude and coherency are zero, may be rejected at the 5% level if W ω>T. Tests at two frequencies separated by more than the bandwidth may be taken to be independent.
The confidence limits on A ω are strictly appropriate only at frequencies for which the coherency is significant. The same applies to the confidence limits on W ω which are however calculated at all frequencies using the approximation that arctanh W l is Normal with variance 1/d.

4 References

Bloomfield P (1976) Fourier Analysis of Time Series: An Introduction Wiley
Jenkins G M and Watts D G (1968) Spectral Analysis and its Applications Holden–Day

5 Arguments

1:   XG NG – REAL (KIND=nag_wp) arrayInput
On entry: the NG univariate spectral estimates, f xx ω, for the x series.
2:   YG NG – REAL (KIND=nag_wp) arrayInput
On entry: the NG univariate spectral estimates, f yy ω, for the y series.
3:   XYRG NG – REAL (KIND=nag_wp) arrayInput
On entry: the real parts, cf ω, of the NG bivariate spectral estimates for the x and y series. The x series leads the y series.
4:   XYIG NG – REAL (KIND=nag_wp) arrayInput
On entry: the imaginary parts, qf ω, of the NG bivariate spectral estimates for the x and y series. The x series leads the y series.
Note: the two univariate and the bivariate spectra must each have been calculated using the same method of smoothing. For rectangular, Bartlett, Tukey or Parzen smoothing windows, the same cut-off point of lag window and the same frequency division of the spectral estimates must be used. For the trapezium frequency smoothing window, the frequency width and the shape of the window and the frequency division of the spectral estimates must be the same. The spectral estimates and statistics must also be unlogged.
5:   NG – INTEGERInput
On entry: the number of spectral estimates in each of the arrays XG, YG, XYRG and XYIG. It is also the number of cross amplitude spectral and squared coherency estimates.
Constraint: NG≥1.
6:   STATS 4 – REAL (KIND=nag_wp) arrayInput
On entry: the four associated statistics for the univariate spectral estimates for the x and y series. STATS 1 contains the degrees of freedom, STATS 2 and STATS 3 contain the lower and upper bound multiplying factors respectively and STATS 4 contains the bandwidth.
Constraints:
  • STATS 1≥3.0;
  • 0.0<STATS 2≤1.0;
  • STATS 3≥1.0.
7:   CA NG – REAL (KIND=nag_wp) arrayOutput
On exit: the NG cross amplitude spectral estimates A^ω at each frequency of ω.
8:   CALW NG – REAL (KIND=nag_wp) arrayOutput
On exit: the NG lower bounds for the NG cross amplitude spectral estimates.
9:   CAUP NG – REAL (KIND=nag_wp) arrayOutput
On exit: the NG upper bounds for the NG cross amplitude spectral estimates.
10:   T – REAL (KIND=nag_wp)Output
On exit: the critical value for the significance of the squared coherency, T.
11:   SC NG – REAL (KIND=nag_wp) arrayOutput
On exit: the NG squared coherency estimates, W^ω at each frequency ω.
12:   SCLW NG – REAL (KIND=nag_wp) arrayOutput
On exit: the NG lower bounds for the NG squared coherency estimates.
13:   SCUP NG – REAL (KIND=nag_wp) arrayOutput
On exit: the NG upper bounds for the NG squared coherency estimates.
14:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | NG<1,
or | STATS 1<3.0,
or | STATS 2≤0.0,
or | STATS 2>1.0,
or | STATS 3<1.0.
IFAIL=2
A bivariate spectral estimate is zero. For this frequency the cross amplitude spectrum and squared coherency and their bounds are set to zero.
IFAIL=3
A univariate spectral estimate is negative. For this frequency the cross amplitude spectrum and squared coherency and their bounds are set to zero.
IFAIL=4
A univariate spectral estimate is zero. For this frequency the cross amplitude spectrum and squared coherency and their bounds are set to zero.
IFAIL=5
A calculated value of the squared coherency exceeds 1.0. For this frequency the squared coherency is reset to 1.0 and this value for the squared coherency is used in the formulae for the calculation of bounds for both the cross amplitude spectrum and squared coherency. This has the consequence that both squared coherency bounds are 1.0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.
If more than one failure of the types 2, 3, 4 and 5 occurs then the failure type which occurred at lowest frequency is returned in IFAIL. However the actions indicated above are also carried out for failures at higher frequencies.

7 Accuracy

All computations are very stable and yield good accuracy.

8 Parallelism and Performance

G13CEF is not threaded in any implementation.

9 Further Comments

The time taken by G13CEF is approximately proportional to NG.

10 Example

This example reads the set of univariate spectrum statistics, the two univariate spectra and the cross spectrum at a frequency division of 2 π 20 for a pair of time series. It calls G13CEF to calculate the cross amplitude spectrum and squared coherency and their bounds and prints the results.

10.1 Program Text

Program Text (g13cefe.f90)

10.2 Program Data

Program Data (g13cefe.d)

10.3 Program Results

Program Results (g13cefe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13CFF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13CFF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

For a bivariate time series, G13CFF calculates the gain and phase together with lower and upper bounds from the univariate and bivariate spectra.

2 Specification

SUBROUTINE G13CFF ( XG, YG, XYRG, XYIG, NG, STATS, GN, GNLW, GNUP, PH, PHLW, PHUP, IFAIL)
INTEGER | NG, IFAIL
REAL (KIND=nag_wp) | XG(NG), YG(NG), XYRG(NG), XYIG(NG), STATS(4), GN(NG), GNLW(NG), GNUP(NG), PH(NG), PHLW(NG), PHUP(NG)

3 Description

Estimates of the gain G ω and phase ϕ ω of the dependency of series y on series x at frequency ω are given by
G^ω= A ω f xx ω ϕ^ω=arccos cf ω A ω , if ​qf ω≥0 ϕ^ω=2 π-arccos cf ω A ω , if ​qf ω<0.
The quantities used in these definitions are obtained as in Section 3 in G13CEF.
Confidence limits are returned for both gain and phase, but should again be taken as very approximate when the coherency W ω, as calculated by G13CEF, is not significant. These are based on the assumption that both G^ω/G ω-1 and ϕ^ω are Normal with variance
1 d 1 W ω -1 .
Although the estimate of ϕ ω is always given in the range 0,2 π, no attempt is made to restrict its confidence limits to this range.

4 References

Bloomfield P (1976) Fourier Analysis of Time Series: An Introduction Wiley
Jenkins G M and Watts D G (1968) Spectral Analysis and its Applications Holden–Day

5 Arguments

1:   XG NG – REAL (KIND=nag_wp) arrayInput
On entry: the NG univariate spectral estimates, f xx ω, for the x series.
2:   YG NG – REAL (KIND=nag_wp) arrayInput
On entry: the NG univariate spectral estimates, f yy ω, for the y series.
3:   XYRG NG – REAL (KIND=nag_wp) arrayInput
On entry: the real parts, cf ω, of the NG bivariate spectral estimates for the x and y series. The x series leads the y series.
4:   XYIG NG – REAL (KIND=nag_wp) arrayInput
On entry: the imaginary parts, qf ω, of the NG bivariate spectral estimates for the x and y series. The x series leads the y series.
Note: the two univariate and the bivariate spectra must each have been calculated using the same method of smoothing. For rectangular, Bartlett, Tukey or Parzen smoothing windows, the same cut-off point of lag window and the same frequency division of the spectral estimates must be used. For the trapezium frequency smoothing window, the frequency width and the shape of the window and the frequency division of the spectral estimates must be the same. The spectral estimates and statistics must also be unlogged.
5:   NG – INTEGERInput
On entry: the number of spectral estimates in each of the arrays XG, YG, XYRG and XYIG. It is also the number of gain and phase estimates.
Constraint: NG≥1.
6:   STATS 4 – REAL (KIND=nag_wp) arrayInput
On entry: the four associated statistics for the univariate spectral estimates for the x and y series. STATS 1 contains the degrees of freedom, STATS 2 and STATS 3 contain the lower and upper bound multiplying factors respectively and STATS 4 holds the bandwidth.
Constraint: STATS 1≥3.0.
7:   GN NG – REAL (KIND=nag_wp) arrayOutput
On exit: the NG gain estimates, G^ω, at each frequency ω.
8:   GNLW NG – REAL (KIND=nag_wp) arrayOutput
On exit: the NG lower bounds for the NG gain estimates.
9:   GNUP NG – REAL (KIND=nag_wp) arrayOutput
On exit: the NG upper bounds for the NG gain estimates.
10:   PH NG – REAL (KIND=nag_wp) arrayOutput
On exit: the NG phase estimates, ϕ^ω, at each frequency ω.
11:   PHLW NG – REAL (KIND=nag_wp) arrayOutput
On exit: the NG lower bounds for the NG phase estimates.
12:   PHUP NG – REAL (KIND=nag_wp) arrayOutput
On exit: the NG upper bounds for the NG phase estimates.
13:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | NG<1,
or | STATS 1<3.0.
IFAIL=2
A bivariate spectral estimate is zero. For this frequency the gain and the phase and their bounds are set to zero.
IFAIL=3
A univariate spectral estimate is negative. For this frequency the gain and the phase and their bounds are set to zero.
IFAIL=4
A univariate spectral estimate is zero. For this frequency the gain and the phase and their bounds are set to zero.
IFAIL=5
A calculated value of the squared coherency exceeds 1.0. For this frequency the squared coherency is reset to 1.0 in the formulae for the gain and phase bounds.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.
If more than one failure of types 2, 3, 4 and 5 occurs then the failure type which occurred at lowest frequency is returned in IFAIL. However the actions indicated above are also carried out for failures at higher frequencies.

7 Accuracy

All computations are very stable and yield good accuracy.

8 Parallelism and Performance

G13CFF is not threaded in any implementation.

9 Further Comments

The time taken by G13CFF is approximately proportional to NG.

10 Example

This example reads the set of univariate spectrum statistics, the two univariate spectra and the cross spectrum at a frequency division of 2 π 20 for a pair of time series. It calls G13CFF to calculate the gain and the phase and their bounds and prints the results.

10.1 Program Text

Program Text (g13cffe.f90)

10.2 Program Data

Program Data (g13cffe.d)

10.3 Program Results

Program Results (g13cffe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13CGF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13CGF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

For a bivariate time series, G13CGF calculates the noise spectrum together with multiplying factors for the bounds and the impulse response function and its standard error, from the univariate and bivariate spectra.

2 Specification

SUBROUTINE G13CGF ( XG, YG, XYRG, XYIG, NG, STATS, L, N, ER, ERLW, ERUP, RF, RFSE, IFAIL)
INTEGER | NG, L, N, IFAIL
REAL (KIND=nag_wp) | XG(NG), YG(NG), XYRG(NG), XYIG(NG), STATS(4), ER(NG), ERLW, ERUP, RF(L), RFSE

3 Description

An estimate of the noise spectrum in the dependence of series y on series x at frequency ω is given by
f y∣x ω=f yy ω1-W ω,
where W ω is the squared coherency described in G13CEF and f yy ω is the univariate spectrum estimate for series y. Confidence limits on the true spectrum are obtained using multipliers as described for G13CAF, but based on d-2 degrees of freedom.
If the dependence of yt on xt can be assumed to be represented in the time domain by the one sided relationship
yt=v 0xt+v 1x t-1+⋯+nt,
where the noise nt is independent of xt, then it is the spectrum of this noise which is estimated by f y∣x ω.
Estimates of the impulse response function v 0,v 1,v 2,… may also be obtained as
vk=1 π∫0 π Re exp ikω f xy ω f xx ω ,
where Re indicates the real part of the expression. For this purpose it is essential that the univariate spectrum for x, f xx ω, and the cross spectrum, f xy ω, be supplied to this routine for a frequency range
ωl=2 πl L ,  0≤l≤L/2,
where denotes the integer part, the integral being approximated by a finite Fourier transform.
An approximate standard error is calculated for the estimates vk. Significant values of vk in the locations described as anticipatory responses in the argument array RF indicate that feedback exists from yt to xt. This will bias the estimates of vk in any causal dependence of yt on xt,x t-1,….

4 References

Bloomfield P (1976) Fourier Analysis of Time Series: An Introduction Wiley
Jenkins G M and Watts D G (1968) Spectral Analysis and its Applications Holden–Day

5 Arguments

1:   XG NG – REAL (KIND=nag_wp) arrayInput
On entry: the NG univariate spectral estimates, f xx ω, for the x series.
2:   YG NG – REAL (KIND=nag_wp) arrayInput
On entry: the NG univariate spectral estimates, f yy ω, for the y series.
3:   XYRG NG – REAL (KIND=nag_wp) arrayInput
On entry: the real parts, cf ω, of the NG bivariate spectral estimates for the x and y series. The x series leads the y series.
4:   XYIG NG – REAL (KIND=nag_wp) arrayInput
On entry: the imaginary parts, qf ω, of the NG bivariate spectral estimates for the x and y series. The x series leads the y series.
Note: the two univariate and the bivariate spectra must each have been calculated using the same method of smoothing. For rectangular, Bartlett, Tukey or Parzen smoothing windows, the same cut-off point of lag window and the same frequency division of the spectral estimates must be used. For the trapezium frequency smoothing window, the frequency width and the shape of the window and the frequency division of the spectral estimates must be the same. The spectral estimates and statistics must also be unlogged.
5:   NG – INTEGERInput
On entry: the number of spectral estimates in each of the arrays XG, YG, XYRG, XYIG. It is also the number of noise spectral estimates.
Constraint: NG≥1.
6:   STATS 4 – REAL (KIND=nag_wp) arrayInput
On entry: the four associated statistics for the univariate spectral estimates for the x and y series. STATS 1 contains the degree of freedom, STATS 2 and STATS 3 contain the lower and upper bound multiplying factors respectively and STATS 4 contains the bandwidth.
Constraints:
  • STATS 1≥3.0;
  • 0.0<STATS 2≤1.0;
  • STATS 3≥1.0.
7:   L – INTEGERInput
On entry: L, the frequency division of the spectral estimates as 2 π L . It is also the order of the FFT used to calculate the impulse response function. L must relate to the parameter NG by the relationship.
Constraint: NG=L/2+1.
8:   N – INTEGERInput
On entry: the number of points in each of the time series x and y. N should have the same value as NXY in the call of G13CCF or G13CDF which calculated the smoothed sample cross spectrum. N is used in calculating the impulse response function standard error (RFSE).
Constraint: N≥1.
9:   ER NG – REAL (KIND=nag_wp) arrayOutput
On exit: the NG estimates of the noise spectrum, f^y∣x ω at each frequency.
10:   ERLW – REAL (KIND=nag_wp)Output
On exit: the noise spectrum lower limit multiplying factor.
11:   ERUP – REAL (KIND=nag_wp)Output
On exit: the noise spectrum upper limit multiplying factor.
12:   RF L – REAL (KIND=nag_wp) arrayOutput
On exit: the impulse response function. Causal responses are stored in ascending frequency in RF 1 to RF NG and anticipatory responses are stored in descending frequency in RF NG+1 to RF L.
13:   RFSE – REAL (KIND=nag_wp)Output
On exit: the impulse response function standard error.
14:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if IFAIL≠0 on exit, the recommended value is -1. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Note: G13CGF may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the routine:
IFAIL=1
On entry, N=value.
Constraint: N≥1.
On entry, NG=value.
Constraint: NG≥1.
On entry, STATS 1=value.
Constraint: STATS 1≥3.0.
On entry, STATS 2=value.
Constraint: STATS 2>0.0.
On entry, STATS 2=value.
Constraint: STATS 2≤1.0.
On entry, STATS 3=value.
Constraint: STATS 3≥1.0.
IFAIL=2
A bivariate spectral estimate is zero.
For this frequency the noise spectrum is set to zero, and the contribution to the impulse response function and its standard error is set to zero.
IFAIL=3
A univariate spectral estimate is negative.
For this frequency the noise spectrum is set to zero, and the contributions to the impulse response function and its standard error are set to zero.
IFAIL=4
A univariate spectral estimate is zero.
For this frequency the noise spectrum is set to zero and the contributions to the impulse response function and its standard error are set to zero.
IFAIL=5
A calculated value of the squared coherency exceeds 1.0.
For this frequency the squared coherency is reset to 1.0 with the consequence that the noise spectrum is zero and the contribution to the impulse response function at this frequency is zero.
IFAIL=6
On entry, NG=value and L=value.
Constraint: NG=L/2+1.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.
If more than one failure of types 2, 3, 4 and 5 occurs then the failure type which occurred at lowest frequency is returned in IFAIL. However the actions indicated above are also carried out for failures at higher frequencies.

7 Accuracy

The computation of the noise is stable and yields good accuracy. The FFT is a numerically stable process, and any errors introduced during the computation will normally be insignificant compared with uncertainty in the data.

8 Parallelism and Performance

G13CGF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13CGF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

The time taken by G13CGF is approximately proportional to NG.

10 Example

This example reads the set of univariate spectrum statistics, the two univariate spectra and the cross spectrum at a frequency division of 2 π 20 for a pair of time series. It calls G13CGF to calculate the noise spectrum and its confidence limits multiplying factors, the impulse response function and its standard error. It then prints the results.

10.1 Program Text

Program Text (g13cgfe.f90)

10.2 Program Data

Program Data (g13cgfe.d)

10.3 Program Results

Program Results (g13cgfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13 Chapter Contents : NAG Library Manual, Mark 26

G13 Chapter Introduction

NAG Library Chapter Contents

G13 – Time Series Analysis

G13 Chapter Introduction – a description of the Chapter and an overview of the algorithms available

Routine Name | Mark of Introduction | Purpose
G13AAF Example Text Example Data | 9 | nagf_tsa_uni_diff Univariate time series, seasonal and non-seasonal differencing
G13ABF Example Text Example Data Example Plot | 9 | nagf_tsa_uni_autocorr Univariate time series, sample autocorrelation function
G13ACF Example Text Example Data Example Plot | 9 | nagf_tsa_uni_autocorr_part Univariate time series, partial autocorrelations from autocorrelations
G13ADF Example Text Example Data | 9 | nagf_tsa_uni_arima_prelim Univariate time series, preliminary estimation, seasonal ARIMA model
G13AEF Example Text Example Data | 9 | nagf_tsa_uni_arima_estim Univariate time series, estimation, seasonal ARIMA model (comprehensive)
G13AFF Example Text Example Data | 9 | nagf_tsa_uni_arima_estim_easy Univariate time series, estimation, seasonal ARIMA model (easy-to-use)
G13AGF Example Text Example Data | 9 | nagf_tsa_uni_arima_update Univariate time series, update state set for forecasting
G13AHF Example Text Example Data | 9 | nagf_tsa_uni_arima_forecast_state Univariate time series, forecasting from state set
G13AJF Example Text Example Data | 10 | nagf_tsa_uni_arima_forcecast Univariate time series, state set and forecasts, from fully specified seasonal ARIMA model
G13AMF Example Text Example Data | 22 | nagf_tsa_uni_smooth_exp Univariate time series, exponential smoothing
G13ASF Example Text Example Data | 13 | nagf_tsa_uni_arima_resid Univariate time series, diagnostic checking of residuals, following G13AEF or G13AFF
G13AUF Example Text Example Data Example Plot | 14 | nagf_tsa_uni_means Computes quantities needed for range-mean or standard deviation-mean plot
G13AWF Example Text Example Data | 25 | nagf_tsa_uni_dickey_fuller_unit Computes (augmented) Dickey–Fuller unit root test statistic
G13BAF Example Text Example Data | 10 | nagf_tsa_multi_filter_arima Multivariate time series, filtering (pre-whitening) by an ARIMA model
G13BBF Example Text Example Data | 11 | nagf_tsa_multi_filter_transf Multivariate time series, filtering by a transfer function model
G13BCF Example Text Example Data | 10 | nagf_tsa_multi_xcorr Multivariate time series, cross-correlations
G13BDF Example Text Example Data | 11 | nagf_tsa_multi_transf_prelim Multivariate time series, preliminary estimation of transfer function model
G13BEF Example Text Example Data | 11 | nagf_tsa_multi_inputmod_estim Multivariate time series, estimation of multi-input model
G13BGF Example Text Example Data | 11 | nagf_tsa_multi_inputmod_update Multivariate time series, update state set for forecasting from multi-input model
G13BHF Example Text Example Data | 11 | nagf_tsa_multi_inputmod_forecast_state Multivariate time series, forecasting from state set of multi-input model
G13BJF Example Text Example Data | 11 | nagf_tsa_multi_inputmod_forecast Multivariate time series, state set and forecasts from fully specified multi-input model
G13CAF Example Text Example Data | 10 | nagf_tsa_uni_spectrum_lag Univariate time series, smoothed sample spectrum using rectangular, Bartlett, Tukey or Parzen lag window
G13CBF Example Text Example Data | 10 | nagf_tsa_uni_spectrum_daniell Univariate time series, smoothed sample spectrum using spectral smoothing by the trapezium frequency (Daniell) window
G13CCF Example Text Example Data | 10 | nagf_tsa_multi_spectrum_lag Multivariate time series, smoothed sample cross spectrum using rectangular, Bartlett, Tukey or Parzen lag window
G13CDF Example Text Example Data | 10 | nagf_tsa_multi_spectrum_daniell Multivariate time series, smoothed sample cross spectrum using spectral smoothing by the trapezium frequency (Daniell) window
G13CEF Example Text Example Data | 10 | nagf_tsa_multi_spectrum_bivar Multivariate time series, cross amplitude spectrum, squared coherency, bounds, univariate and bivariate (cross) spectra
G13CFF Example Text Example Data | 10 | nagf_tsa_multi_gain_bivar Multivariate time series, gain, phase, bounds, univariate and bivariate (cross) spectra
G13CGF Example Text Example Data | 10 | nagf_tsa_multi_noise_bivar Multivariate time series, noise spectrum, bounds, impulse response function and its standard error
G13DBF Example Text Example Data | 11 | nagf_tsa_multi_autocorr_part Multivariate time series, multiple squared partial autocorrelations
G13DDF Example Text Example Data | 22 | nagf_tsa_multi_varma_estimate Multivariate time series, estimation of VARMA model
G13DJF Example Text Example Data | 15 | nagf_tsa_multi_varma_forecast Multivariate time series, forecasts and their standard errors
G13DKF Example Text Example Data | 15 | nagf_tsa_multi_varma_update Multivariate time series, updates forecasts and their standard errors
G13DLF Example Text Example Data | 15 | nagf_tsa_multi_diff Multivariate time series, differences and/or transforms
G13DMF Example Text Example Data | 15 | nagf_tsa_multi_corrmat_cross Multivariate time series, sample cross-correlation or cross-covariance matrices
G13DNF Example Text Example Data | 15 | nagf_tsa_multi_corrmat_partlag Multivariate time series, sample partial lag correlation matrices, χ 2 statistics and significance levels
G13DPF Example Text Example Data | 16 | nagf_tsa_multi_regmat_partial Multivariate time series, partial autoregression matrices
G13DSF Example Text Example Data | 13 | nagf_tsa_multi_varma_diag Multivariate time series, diagnostic checking of residuals, following G13DDF
G13DXF Example Text Example Data | 15 | nagf_tsa_uni_arma_roots Calculates the zeros of a vector autoregressive (or moving average) operator
G13EAF Example Text Example Data | 17 | nagf_tsa_multi_kalman_sqrt_var Combined measurement and time update, one iteration of Kalman filter, time-varying, square root covariance filter
G13EBF Example Text Example Data | 17 | nagf_tsa_multi_kalman_sqrt_invar Combined measurement and time update, one iteration of Kalman filter, time-invariant, square root covariance filter
G13EJF Example Text Example Data Example Plot | 25 | nagf_tsa_kalman_unscented_state_revcom Combined time and measurement update, one iteration of the Unscented Kalman Filter for a nonlinear state space model, with additive noise (reverse communication)
G13EKF Example Text Example Data Example Plot | 25 | nagf_tsa_kalman_unscented_state Combined time and measurement update, one iteration of the Unscented Kalman Filter for a nonlinear state space model, with additive noise
G13FAF Example Text Example Data | 20 | nagf_tsa_uni_garch_asym1_estim Univariate time series, parameter estimation for either a symmetric GARCH process or a GARCH process with asymmetry of the form ε t-1+γ 2
G13FBF | 20 | nagf_tsa_uni_garch_asym1_forecast Univariate time series, forecast function for either a symmetric GARCH process or a GARCH process with asymmetry of the form ε t-1+γ 2
G13FCF Example Text Example Data | 20 | nagf_tsa_uni_garch_asym2_estim Univariate time series, parameter estimation for a GARCH process with asymmetry of the form ε t-1+γ ε t-1 2
G13FDF | 20 | nagf_tsa_uni_garch_asym2_forecast Univariate time series, forecast function for a GARCH process with asymmetry of the form ε t-1+γ ε t-1 2
G13FEF Example Text Example Data | 20 | nagf_tsa_uni_garch_GJR_estim Univariate time series, parameter estimation for an asymmetric Glosten, Jagannathan and Runkle (GJR) GARCH process
G13FFF | 20 | nagf_tsa_uni_garch_GJR_forecast Univariate time series, forecast function for an asymmetric Glosten, Jagannathan and Runkle (GJR) GARCH process
G13FGF Example Text Example Data | 20 | nagf_tsa_uni_garch_exp_estim Univariate time series, parameter estimation for an exponential GARCH (EGARCH) process
G13FHF | 20 | nagf_tsa_uni_garch_exp_forecast Univariate time series, forecast function for an exponential GARCH (EGARCH) process
G13MEF Example Text Example Data Example Plot | 24 | nagf_tsa_inhom_iema Computes the iterated exponential moving average for a univariate inhomogeneous time series
G13MFF Example Text Example Data | 24 | nagf_tsa_inhom_iema_all Computes the iterated exponential moving average for a univariate inhomogeneous time series, intermediate results are also returned
G13MGF Example Text Example Data | 24 | nagf_tsa_inhom_ma Computes the exponential moving average for a univariate inhomogeneous time series
G13NAF Example Text Example Data Example Plot | 25 | nagf_tsa_cp_pelt Change point detection, using the PELT algorithm
G13NBF Example Text Example Data Example Plot | 25 | nagf_tsa_cp_pelt_user Change points detection using the PELT algorithm, user supplied cost function
G13NDF Example Text Example Data Example Plot | 25 | nagf_tsa_cp_binary Change point detection, using binary segmentation
G13NEF Example Text Example Data Example Plot | 25 | nagf_tsa_cp_binary_user Change point detection, using binary segmentation, user supplied cost function
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13DBF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13DBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13DBF calculates the multivariate partial autocorrelation function of a multivariate time series.

2 Specification

SUBROUTINE G13DBF ( C0, C, LDC0, NS, NL, NK, P, V0, V, D, DB, W, WB, NVP, WA, IWA, IFAIL)
INTEGER | LDC0, NS, NL, NK, NVP, IWA, IFAIL
REAL (KIND=nag_wp) | C0(LDC0,NS), C(LDC0,LDC0,NL), P(NK), V0, V(NK), D(LDC0,LDC0,NK), DB(LDC0,NS), W(LDC0,LDC0,NK), WB(LDC0,LDC0,NK), WA(IWA)

3 Description

The input is a set of lagged autocovariance matrices C 0,C 1,C 2,…,Cm. These will generally be sample values such as are obtained from a multivariate time series using G13DMF.
The main calculation is the recursive determination of the coefficients in the finite lag (forward) prediction equation
xt = Φ l,1 x t-1 +⋯+ Φ l,l x t-l + e l,t
and the associated backward prediction equation
x t-l- 1=Ψ l,1x t-l+⋯+Ψ l,lx t- 1+f l,t
together with the covariance matrices Dl of e l,t and Gl of f l,t.
The recursive cycle, by which the order of the prediction equation is extended from l to l+1, is to calculate
M l+1 = C l+1 T - Φ l,1 ClT -⋯- Φ l,l C 1 T (1)
then Φ l+1,l+1 = M l+1 Dl-1 ,   Ψ l+1,l+1 = MT l+1 Gl-1
from which
Φ l+1,j=Φ l,j-Φ l+1,l+1Ψ l,l+1-j,   j=1,2,…,l (2)
and
Ψ l+1,j=Ψ l,j-Ψ l+1,l+1Φ l,l+1-j,  j=1,2,…,l. (3)
Finally, D l+1=Dl-M l+1ΦT l+1,l+1 and G l+1=Gl-MT l+1ΨT l+1,l+1.
(Here T denotes the transpose of a matrix.)
The cycle is initialized by taking (for l=0)
D 0=G 0=C 0.
In the step from l=0 to 1, the above equations contain redundant terms and simplify. Thus (1) becomes M 1=CT 1 and neither (2) or (3) are needed.
Quantities useful in assessing the effectiveness of the prediction equation are generalized variance ratios
vl = det⁡Dl / det⁡C 0 ,   l=1,2,…
and multiple squared partial autocorrelations
pl 2 = 1 - vl / v l-1 .

4 References

Akaike H (1971) Autoregressive model fitting for control Ann. Inst. Statist. Math. 23 163–180
Whittle P (1963) On the fitting of multivariate autoregressions and the approximate canonical factorization of a spectral density matrix Biometrika 50 129–134

5 Arguments

1:   C0 LDC0NS – REAL (KIND=nag_wp) arrayInput
On entry: contains the zero lag cross-covariances between the NS series as returned by G13DMF. (C0 is assumed to be symmetric, upper triangle only is used.)
2:   C LDC0LDC0NL – REAL (KIND=nag_wp) arrayInput
On entry: contains the cross-covariances at lags 1 to NL. C ijk must contain the cross-covariance, c ijk, of series i and series j at lag k. Series j leads series i.
3:   LDC0 – INTEGERInput
On entry: the first dimension of the arrays C0, C, D, DB, W and WB and the second dimension of the arrays C, D, W and WB as declared in the (sub)program from which G13DBF is called.
Constraint: LDC0≥max NS,1.
4:   NS – INTEGERInput
On entry: k, the number of time series whose cross-covariances are supplied in C and C0.
Constraint: NS≥1.
5:   NL – INTEGERInput
On entry: m, the maximum lag for which cross-covariances are supplied in C.
Constraint: NL≥1.
6:   NK – INTEGERInput
On entry: the number of lags to which partial auto-correlations are to be calculated.
Constraint: 1≤NK≤NL.
7:   P NK – REAL (KIND=nag_wp) arrayOutput
On exit: the multiple squared partial autocorrelations from lags 1 to NVP; that is, P l contains pl 2, for l=1,2,…,NVP. For lags NVP+1 to NK the elements of P are set to zero.
8:   V0 – REAL (KIND=nag_wp)Output
On exit: the lag zero prediction error variance (equal to the determinant of C0).
9:   V NK – REAL (KIND=nag_wp) arrayOutput
On exit: the prediction error variance ratios from lags 1 to NVP; that is, V l contains vl, for l=1,2,…,NVP. For lags NVP+1 to NK the elements of V are set to zero.
10:   D LDC0LDC0NK – REAL (KIND=nag_wp) arrayOutput
On exit: the prediction error variance matrices at lags 1 to NVP.
Element i,j,k of D contains the prediction error covariance of series i and series j at lag k, for k=1,2,…,NVP. Series j leads series i; that is, the i,jth element of Dk. For lags NVP+1 to NK the elements of D are set to zero.
11:   DB LDC0NS – REAL (KIND=nag_wp) arrayOutput
On exit: the backward prediction error variance matrix at lag NVP.
DB ij contains the backward prediction error covariance of series i and series j; that is, the i,jth element of the Gk, where k=NVP.
12:   W LDC0LDC0NK – REAL (KIND=nag_wp) arrayOutput
On exit: the prediction coefficient matrices at lags 1 to NVP.
W ijl contains the jth prediction coefficient of series i at lag l; that is, the i,jth element of Φ kl, where k=NVP, for l=1,2,…,NVP. For lags NVP+1 to NK the elements of W are set to zero.
13:   WB LDC0LDC0NK – REAL (KIND=nag_wp) arrayOutput
On exit: the backward prediction coefficient matrices at lags 1 to NVP.
WB ijl contains the jth backward prediction coefficient of series i at lag l; that is, the i,jth element of Ψ kl, where k=NVP, for l=1,2,…,NVP. For lags NVP+1 to NK the elements of WB are set to zero.
14:   NVP – INTEGEROutput
On exit: the maximum lag, L, for which calculation of P, V, D, DB, W and WB was successful. If the routine completes successfully NVP will equal NK.
15:   WA IWA – REAL (KIND=nag_wp) arrayWorkspace
16:   IWA – INTEGERInput
On entry: the dimension of the array WA as declared in the (sub)program from which G13DBF is called.
Constraint: IWA≥2×NS+1×NS.
17:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | LDC0<1,
or | NS<1,
or | NS>LDC0,
or | NL<1,
or | NK<1,
or | NK>NL,
or | IWA<2×NS+1×NS.
IFAIL=2
C0 is not positive definite.
V0, V, P, D, DB, W, WB and NVP are set to zero.
IFAIL=3
At lag k=NVP+1≤NK, Dk was found not to be positive definite. Up to lag NVP, V0, V, P, D, W and WB contain the values calculated so far and from lag NVP+1 to lag NK the matrices contain zero. DB contains the backward prediction coefficients for lag NVP.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The conditioning of the problem depends on the prediction error variance ratios. Very small values of these may indicate loss of accuracy in the computations.

8 Parallelism and Performance

G13DBF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13DBF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

The time taken by G13DBF is roughly proportional to NK 2×NS 3.
If sample autocorrelation matrices are used as input, then the output will be relevant to the original series scaled by their standard deviations. If these autocorrelation matrices are produced by G13DMF, you must replace the diagonal elements of C 0 (otherwise used to hold the series variances) by 1.

10 Example

This example reads the autocovariance matrices for four series from lag 0 to 5. It calls G13DBF to calculate the multivariate partial autocorrelation function and other related matrices of statistics up to lag 3. It prints the results.

10.1 Program Text

Program Text (g13dbfe.f90)

10.2 Program Data

Program Data (g13dbfe.d)

10.3 Program Results

Program Results (g13dbfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13DDF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13DDF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
▸▿ 9 Further Comments
9.1 Memory Usage
9.2 Timing
9.3 Constraining for Stationarity and Invertibility
9.4 Over-parameterisation
9.5 Standardizing the Residual Series
9.6 Assessing the Fit of the Model
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13DDF fits a vector autoregressive moving average (VARMA) model to an observed vector of time series using the method of Maximum Likelihood (ML). Standard errors of parameter estimates are computed along with their appropriate correlation matrix. The routine also calculates estimates of the residual series.

2 Specification

SUBROUTINE G13DDF ( K, N, IP, IQ, MEAN, PAR, NPAR, QQ, KMAX, W, PARHLD, EXACT, IPRINT, CGETOL, MAXCAL, ISHOW, NITER, RLOGL, V, G, CM, LDCM, IFAIL)
INTEGER | K, N, IP, IQ, NPAR, KMAX, IPRINT, MAXCAL, ISHOW, NITER, LDCM, IFAIL
REAL (KIND=nag_wp) | PAR(NPAR), QQ(KMAX,K), W(KMAX,N), CGETOL, RLOGL, V(KMAX,N), G(NPAR), CM(LDCM,NPAR)
LOGICAL | MEAN, PARHLD(NPAR), EXACT

3 Description

Let Wt = w 1 t,w 2 t,…,w kt T , for t=1,2,…,n, denote a vector of k time series which is assumed to follow a multivariate ARMA model of the form
Wt-μ= ϕ 1 W t-1-μ+ϕ 2 W t-2-μ+⋯+ϕp W t-p-μ +εt-θ 1ε t-1-θ 2ε t-2-⋯-θqε t-q (1)
where εt = ε 1 t,ε 2 t,…,ε kt T , for t=1,2,…,n, is a vector of k residual series assumed to be Normally distributed with zero mean and positive definite covariance matrix Σ. The components of εt are assumed to be uncorrelated at non-simultaneous lags. The ϕi and θj are k by k matrices of parameters. ϕi, for i=1,2,…,p, are called the autoregressive (AR) parameter matrices, and θi, for i=1,2,…,q, the moving average (MA) parameter matrices. The parameters in the model are thus the p (k by k) ϕ-matrices, the q (k by k) θ-matrices, the mean vector, μ, and the residual error covariance matrix Σ. Let
A ϕ= ϕ 1 I 0 . . . 0 ϕ 2 0 I 0 . . 0 . . . . . . ϕ p-1 0 . . . 0 I ϕp 0 . . . 0 0 pk×pk   and B θ= θ 1 I 0 . . . 0 θ 2 0 I 0 . . 0 . . . . . . θ q-1 0 . . . . I θq 0 . . . . 0 qk×qk
where I denotes the k by k identity matrix.
The ARMA model (1) is said to be stationary if the eigenvalues of A ϕ lie inside the unit circle. Similarly, the ARMA model (1) is said to be invertible if the eigenvalues of B θ lie inside the unit circle.
The method of computing the exact likelihood function (using a Kalman filter algorithm) is discussed in Shea (1987). A quasi-Newton algorithm (see Gill and Murray (1972)) is then used to search for the maximum of the log-likelihood function. Stationarity and invertibility are enforced on the model using the reparameterisation discussed in Ansley and Kohn (1986). Conditional on the maximum likelihood estimates being equal to their true values the estimates of the residual series are uncorrelated with zero mean and constant variance Σ.
You have the option of setting an argument (EXACT to .FALSE.) so that G13DDF calculates conditional maximum likelihood estimates (conditional on W 0=W-1=⋯=W 1-p=ε 0=ε-1=⋯= ε 1-q=0). This may be useful if the exact maximum likelihood estimates are close to the boundary of the invertibility region.
You also have the option (see Section 5) of requesting G13DDF to constrain elements of the ϕ and θ matrices and μ vector to have pre-specified values.

4 References

Ansley C F and Kohn R (1986) A note on reparameterising a vector autoregressive moving average model to enforce stationarity J. Statist. Comput. Simulation 24 99–106
Gill P E and Murray W (1972) Quasi-Newton methods for unconstrained optimization J. Inst. Math. Appl. 9 91–108
Shea B L (1987) Estimation of multivariate time series J. Time Ser. Anal. 8 95–110

5 Arguments

1:   K – INTEGERInput
On entry: k, the number of observed time series.
Constraint: K≥1.
2:   N – INTEGERInput
On entry: n, the number of observations in each time series.
3:   IP – INTEGERInput
On entry: p, the number of AR parameter matrices.
Constraint: IP≥0.
4:   IQ – INTEGERInput
On entry: q, the number of MA parameter matrices.
Constraint: IQ≥0.
IP=IQ=0 is not permitted.
5:   MEAN – LOGICALInput
On entry: MEAN=.TRUE., if components of μ have been estimated and MEAN=.FALSE., if all elements of μ are to be taken as zero.
Constraint: MEAN=.TRUE. or .FALSE..
6:   PAR NPAR – REAL (KIND=nag_wp) arrayInput/Output
On entry: initial parameter estimates read in row by row in the order ϕ 1,ϕ 2,…,ϕp, θ 1,θ 2,…,θq,μ.
Thus,
  • if IP>0, PAR l-1×k×k+i-1×k+j must be set equal to an initial estimate of the i,jth element of ϕl, for l=1,2,…,p, i=1,2,…,k and j=1,2,…,k;
  • if IQ>0, PAR p×k×k+l-1×k×k+i-1×k+j must be set equal to an initial estimate of the i,jth element of θl, l=1,2,…,q and i,j=1,2,…,k;
  • if MEAN=.TRUE., PAR p+q×k×k+i should be set equal to an initial estimate of the ith component of μ (μ i). (If you set PAR p+q×k×k+i to 0.0 then G13DDF will calculate the mean of the ith series and use this as an initial estimate of μ i.)
The first p×k×k elements of PAR must satisfy the stationarity condition and the next q×k×k elements of PAR must satisfy the invertibility condition.
If in doubt set all elements of PAR to 0.0.
On exit: if IFAIL=0 or IFAIL≥4 then all the elements of PAR will be overwritten by the latest estimates of the corresponding ARMA parameters.
7:   NPAR – INTEGERInput
On entry: the dimension of the arrays PAR, PARHLD and G and the second dimension of the array CM as declared in the (sub)program from which G13DDF is called.NPAR is the number of initial parameter estimates.
Constraints:
  • if MEAN=.FALSE., NPAR must be set equal to p+q×k×k;
  • if MEAN=.TRUE., NPAR must be set equal to p+q×k×k+k.
The total number of observations n×k must exceed the total number of parameters in the model (NPAR+k k+1/2).
8:   QQ KMAXK – REAL (KIND=nag_wp) arrayInput/Output
On entry: QQ ij must be set equal to an initial estimate of the i,jth element of Σ. The lower triangle only is needed. QQ must be positive definite. It is strongly recommended that on entry the elements of QQ are of the same order of magnitude as at the solution point. If you set QQ ij=0.0, for i=1,2,…,k and j=1,2,…,i, then G13DDF will calculate the covariance matrix between the k time series and use this as an initial estimate of Σ.
On exit: if IFAIL=0 or IFAIL≥4 then QQ ij will contain the latest estimate of the i,jth element of Σ. The lower triangle only is returned.
9:   KMAX – INTEGERInput
On entry: the first dimension of the arrays QQ, W and V as declared in the (sub)program from which G13DDF is called.
Constraint: KMAX≥K.
10:   W KMAXN – REAL (KIND=nag_wp) arrayInput
On entry: W it must be set equal to the ith component of Wt, for i=1,2,…,k and t=1,2,…,n.
11:   PARHLD NPAR – LOGICAL arrayInput
On entry: PARHLD i must be set to .TRUE. if PAR i is to be held constant at its input value and .FALSE. if PAR i is a free parameter, for i=1,2,…,NPAR.
If in doubt try setting all elements of PARHLD to .FALSE..
12:   EXACT – LOGICALInput
On entry: must be set equal to .TRUE. if you wish G13DDF to compute exact maximum likelihood estimates. EXACT must be set equal to .FALSE. if only conditional likelihood estimates are required.
13:   IPRINT – INTEGERInput
On entry: the frequency with which the automatic monitoring routine is to be called.
IPRINT>0
The ML search procedure is monitored once every IPRINT iterations and just before exit from the search routine.
IPRINT=0
The search routine is monitored once at the final point.
IPRINT<0
The search routine is not monitored at all.
14:   CGETOL – REAL (KIND=nag_wp)Input
On entry: the accuracy to which the solution in PAR and QQ is required.
If CGETOL is set to 10-l and on exit IFAIL=0 or IFAIL≥6, then all the elements in PAR and QQ should be accurate to approximately l decimal places. For most practical purposes the value 10-4 should suffice. You should be wary of setting CGETOL too small since the convergence criteria may then have become too strict for the machine to handle.
If CGETOL has been set to a value which is less than the machine precision, ε, then G13DDF will use the value 10.0×ε instead.
15:   MAXCAL – INTEGERInput
On entry: the maximum number of likelihood evaluations to be permitted by the search procedure.
Suggested value: MAXCAL=40×NPAR×NPAR+5.
Constraint: MAXCAL≥1.
16:   ISHOW – INTEGERInput
On entry: specifies which of the following two quantities are to be printed.
(i) | table of maximum likelihood estimates and their standard errors (as returned in the output arrays PAR, QQ and CM);
(ii) | table of residual series (as returned in the output array V).
ISHOW=0
None of the above are printed.
ISHOW=1
(i) only is printed.
ISHOW=2
(i) and (ii) are printed.
Constraint: 0≤ISHOW≤2.
17:   NITER – INTEGEROutput
On exit: if IFAIL=0 or IFAIL≥4 then NITER contains the number of iterations performed by the search routine.
18:   RLOGL – REAL (KIND=nag_wp)Output
On exit: if IFAIL=0 or IFAIL≥4 then RLOGL contains the value of the log-likelihood function corresponding to the final point held in PAR and QQ.
19:   V KMAXN – REAL (KIND=nag_wp) arrayOutput
On exit: if IFAIL=0 or IFAIL≥4 then V it will contain an estimate of the ith component of εt, for i=1,2,…,k and t=1,2,…,n, corresponding to the final point held in PAR and QQ.
20:   G NPAR – REAL (KIND=nag_wp) arrayOutput
On exit: if IFAIL=0 or IFAIL≥4 then G i will contain the estimated first derivative of the log-likelihood function with respect to the ith element in the array PAR. If the gradient cannot be computed then all the elements of G are returned as zero.
21:   CM LDCMNPAR – REAL (KIND=nag_wp) arrayOutput
On exit: if IFAIL=0 or IFAIL≥4 then CM ij will contain an estimate of the correlation coefficient between the ith and jth elements in the PAR array for 1≤i≤NPAR, 1≤j≤NPAR. If i=j, then CM ij will contain the estimated standard error of PAR i. If the lth component of PAR has been held constant, i.e., PARHLD l was set to .TRUE., then the lth row and column of CM will be set to zero. If the second derivative matrix cannot be computed then all the elements of CM are returned as zero.
22:   LDCM – INTEGERInput
On entry: the first dimension of the array CM as declared in the (sub)program from which G13DDF is called.
Constraint: LDCM≥NPAR.
23:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if IFAIL≠0 on exit, the recommended value is -1. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Note: G13DDF may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the routine:
IFAIL=1
On entry, IP=value.
Constraint: IP≥0.
On entry, IP=0 and IQ=0.
On entry, IQ=value.
Constraint: IQ≥0.
On entry, ISHOW=value.
Constraint: 0≤ISHOW≤2.
On entry, K=value.
Constraint: K≥1.
On entry, KMAX=value and K=value.
Constraint: KMAX≥K.
On entry, LDCM=value and NPAR=value.
Constraint: LDCM≥NPAR.
On entry, MAXCAL=value.
Constraint: MAXCAL≥1.
On entry, N=value, K=value and NPAR=value.
Constraint: N×K>NPAR+K×K+1/2.
On entry, NPAR=value.
Constraint: NPAR=value.
On entry, NPAR=value.
Constraint: NPAR≥0.
IFAIL=2
The initial AR parameter estimates are outside the stationarity region.
To proceed, you must try a different starting point.
The initial estimate of Σ is not positive definite. To proceed, you must try a different starting point.
The initial MA parameter estimates are outside the invertibility region. To proceed, you must try a different starting point.
The starting point is too close to the boundary of the admissibility region.
IFAIL=3
The routine cannot compute a sufficiently accurate estimate of the gradient vector at the user-supplied starting point. This usually occurs if either the initial parameter estimates are very close to the ML parameter estimates, or you have supplied a very poor estimate of Σ, or the starting point is very close to the boundary of the stationarity or invertibility region. To proceed, you must try a different starting point.
IFAIL=4
There have been MAXCAL log-likelihood evaluations made in the routine.
If steady increases in the log-likelihood function were monitored up to the point where this exit occurred, then the exit probably simply occurred because MAXCAL was set too small, so the calculations should be restarted from the final point held in PAR and QQ. This type of exit may also indicate that there is no maximum to the likelihood surface. Output quantities were computed at the final point held in PAR and QQ, except that if G or CM could not be computed, in which case they are set to zero.
IFAIL=5
The conditions for a solution have not all been met, but a point at which the log-likelihood took a larger value could not be found.
Provided that the estimated first derivatives are sufficiently small, and that the estimated condition number of the second derivative (Hessian) matrix, as printed when IPRINT≥0, is not too large, this error exit may simply mean that, although it has not been possible to satisfy the specified requirements, the algorithm has in fact found the solution as far as the accuracy of the machine permits.
Such a condition can arise, for instance, if CGETOL has been set so small that rounding error in evaluating the likelihood function makes attainment of the convergence conditions impossible.
If the estimated condition number at the final point is large, it could be that the final point is a solution but that the smallest eigenvalue of the Hessian matrix is so close to zero at the solution that it is not possible to recognize it as a solution. Output quantities were computed at the final point held in PAR and QQ, except that if G or CM could not be computed, in which case they are set to zero.
IFAIL=6
The ML solution is so close to the boundary of either the stationarity region or the invertibility region that G13DDF cannot evaluate the Hessian matrix. The elements of CM are set to zero, as are the elements of G. All other output quantities are correct.
IFAIL=7
An estimate of the second derivative matrix and the gradient vector at the solution point was computed. Either the Hessian matrix was found to be too ill-conditioned to be evaluated accurately or the gradient vector could not be computed to an acceptable degree of accuracy. The elements of CM are set to zero, as are the elements of G. All other output quantities are correct.
IFAIL=8
The second-derivative matrix at the solution point is not positive definite. The elements of CM are set to zero. All other output quantities are correct.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

On exit from G13DDF, if IFAIL=0 or IFAIL≥6 and CGETOL has been set to 10-l, then all the parameters should be accurate to approximately l decimal places. If CGETOL was set equal to a value less than the machine precision, ε, then all the parameters should be accurate to approximately 10.0×ε.
If IFAIL=4 on exit (i.e., MAXCAL likelihood evaluations have been made but the convergence conditions of the search routine have not been satisfied), then the elements in PAR and QQ may still be good approximations to the ML estimates. Inspection of the elements of G may help you determine whether this is likely.

8 Parallelism and Performance

G13DDF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13DDF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

9.1 Memory Usage

Let r = max IP,IQ and s = NPAR+K× K+1 / 2 . Local workspace arrays of fixed lengths are allocated internally by G13DDF. The total size of these arrays amounts to s+K×r+52 integer elements and 2 × s 2 +s× s-1 /2+15× s+ K 2 × 2×IP+IQ+ r+3 2 +K× 2× r 2 +2× r+3× N+4 +10 real elements.

9.2 Timing

The number of iterations required depends upon the number of parameters in the model and the distance of the user-supplied starting point from the solution.

9.3 Constraining for Stationarity and Invertibility

If the solution lies on the boundary of the admissibility region (stationarity and invertibility region) then G13DDF may get into difficulty and exit with IFAIL=5. If this exit occurs you are advised to either try a different starting point or a different setting for EXACT. If this still continues to occur then you are urged to try fitting a more parsimonious model.

9.4 Over-parameterisation

You are advised to try and avoid fitting models with an excessive number of parameters since over-parameterisation can cause the maximization problem to become ill-conditioned.

9.5 Standardizing the Residual Series

The standardized estimates of the residual series εt (denoted by e^t) can easily be calculated by forming the Cholesky decomposition of Σ, e.g., G GT and setting e^t=G-1 ε^t. F07FDF (DPOTRF) may be used to calculate the array G. The components of e^t which are now uncorrelated at all lags can sometimes be more easily interpreted.

9.6 Assessing the Fit of the Model

If your time series model provides a good fit to the data then the residual series should be approximately white noise, i.e., exhibit no serial cross-correlation. An examination of the residual cross-correlation matrices should confirm whether this is likely to be so. You are advised to call G13DSF to provide information for diagnostic checking. G13DSF returns the residual cross-correlation matrices along with their asymptotic standard errors. G13DSF also computes a portmanteau statistic and its asymptotic significance level for testing model adequacy. If IFAIL=0 or 5≤IFAIL≤8 on exit from G13DDF then the quantities output K, N, V, KMAX, IP, IQ, PAR, PARHLD, and QQ will be suitable for input to G13DSF.

10 Example

This example shows how to fit a bivariate AR(1) model to two series each of length 48. μ will be estimated and ϕ 1 2,1 will be constrained to be zero.

10.1 Program Text

Program Text (g13ddfe.f90)

10.2 Program Data

Program Data (g13ddfe.d)

10.3 Program Results

Program Results (g13ddfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13DJF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13DJF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13DJF computes forecasts of a multivariate time series. It is assumed that a vector ARMA model has already been fitted to the appropriately differenced/transformed time series using G13DDF. The standard deviations of the forecast errors are also returned. A reference vector is set up so that, should future series values become available, the forecasts and their standard errors may be updated by calling G13DKF.

2 Specification

SUBROUTINE G13DJF ( K, N, Z, KMAX, TR, ID, DELTA, IP, IQ, MEAN, PAR, LPAR, QQ, V, LMAX, PREDZ, SEFZ, REF, LREF, WORK, LWORK, IWORK, LIWORK, IFAIL)
INTEGER | K, N, KMAX, ID(K), IP, IQ, LPAR, LMAX, LREF, LWORK, IWORK(LIWORK), LIWORK, IFAIL
REAL (KIND=nag_wp) | Z(KMAX,N), DELTA(KMAX,*), PAR(LPAR), QQ(KMAX,K), V(KMAX,*), PREDZ(KMAX,LMAX), SEFZ(KMAX,LMAX), REF(LREF), WORK(LWORK)
CHARACTER(1) | TR(K), MEAN

3 Description

Let the vector Zt = z 1 t,z 2 t,…,z kt T , for t=1,2,…,n, denote a k-dimensional time series for which forecasts of Z n+1,Z n+2,…,Z n+lmax are required. Let Wt = w 1 t,w 2 t,…,w kt T be defined as follows:
w it=δi B z it*,  i=1,2,…,k,
where δi B is the differencing operator applied to the ith series and where z it* is equal to either z it, z it or loge z it depending on whether or not a transformation was required to stabilize the variance before fitting the model.
If the order of differencing required for the ith series is di, then the differencing operator for the ith series is defined by δi B=1-δ i 1 B-δ i 2 B 2-⋯-δ i di B di where B is the backward shift operator; that is, B Zt=Z t-1. The differencing parameters δ ij, for i=1,2,…,k and j=1,2,…,di, must be supplied by you. If the ith series does not require differencing, then di=0.
Wt is assumed to follow a multivariate ARMA model of the form:
Wt-μ=ϕ 1 W t-1-μ+ϕ 2 W t-2-μ+⋯+ϕp W t-p-μ+εt-θ 1ε t-1-⋯-θqε t-q, (1)
where εt = ε 1 t,ε 2 t,…,ε kt T , for t=1,2,…,n, is a vector of k residual series assumed to be Normally distributed with zero mean and positive definite covariance matrix Σ. The components of εt are assumed to be uncorrelated at non-simultaneous lags. The ϕi and θj are k by k matrices of parameters. The matrices ϕi, for i=1,2,…,p, are the autoregressive (AR) parameter matrices, and the matrices θi, for i=1,2,…,q, the moving average (MA) parameter matrices. The parameters in the model are thus the p (k by k) ϕ-matrices, the q (k by k) θ-matrices, the mean vector μ and the residual error covariance matrix Σ. The ARMA model (1) must be both stationary and invertible; see G13DXF for a method of checking these conditions.
The ARMA model (1) may be rewritten as
ϕ Bδ B Zt*-μ=θ B εt,
where ϕ B and θ B are the autoregressive and moving average polynomials and δ B denotes the k by k diagonal matrix whose ith diagonal elements is δi B and Zt* = z 1 t * , z 2 t* … z kt* T .
This may be rewritten as
ϕ B δ B Zt*=ϕ B μ+θ B εt
or
Zt*=τ+ψ B εt=τ+εt+ψ 1ε t- 1+ψ 2ε t- 2+⋯
where ψ B=δ-1 B ϕ-1 B θ B and τ=δ-1 B μ is a vector of length k.
Forecasts are computed using a multivariate version of the procedure described in Box and Jenkins (1976). If Z^n*l denotes the forecast of Z n+l*, then Z^n*l is taken to be that linear function of Zn*,Z n-1*,… which minimizes the elements of E en l en′l where en l=Z n+l*-Z^n*l is the forecast error. Z^n*l is referred to as the linear minimum mean square error forecast of Z n+l*.
The linear predictor which minimizes the mean square error may be expressed as
Z^n*l=τ+ψlεn+ψ l+1ε n-1+ψ l+2ε n-2+⋯.
The forecast error at t for lead l is then
en l=Z n+l*-Z^n*l=ε n+l+ψ 1ε n+l-1+ψ 2ε n+l-2+⋯+ψ l-1ε n+1.
Let d=max di, for i=1,2,…,k. Unless q=0 the routine requires estimates of εt, for t=d+1,…,n, which are obtainable from G13DDF. The terms εt are assumed to be zero, for t=n+1,…,n+lmax. You may use G13DKF to update these lmax forecasts should further observations, Z n+1,Z n+2,…, become available. Note that when lmax or more further observations are available then G13DJF must be used to produce new forecasts for Z n+lmax+1,Z n+lmax+2,…, should they be required.
When a transformation has been used the forecasts and their standard errors are suitably modified to give results in terms of the original series, Zt; see Granger and Newbold (1976).

4 References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day
Granger C W J and Newbold P (1976) Forecasting transformed series J. Roy. Statist. Soc. Ser. B 38 189–203
Wei W W S (1990) Time Series Analysis: Univariate and Multivariate Methods Addison–Wesley

5 Arguments

The quantities K, N, KMAX, IP, IQ, PAR, NPAR, QQ and V from G13DDF are suitable for input to G13DJF.
1:   K – INTEGERInput
On entry: k, the dimension of the multivariate time series.
Constraint: K≥1.
2:   N – INTEGERInput
On entry: n, the number of observations in the series, Zt, prior to differencing.
Constraint: N≥3.
The total number of observations must exceed the total number of parameters in the model; that is
  • if MEAN='Z', N×K>IP+IQ×K×K+K×K+1/2;
  • if MEAN='M', N×K>IP+IQ×K×K+K+K×K+1/2,
(see the arguments IP, IQ and MEAN).
3:   Z KMAXN – REAL (KIND=nag_wp) arrayInput
On entry: Z it must contain, z it, the ith component of Zt, for i=1,2,…,k and t=1,2,…,n.
Constraints:
  • if TR i='L', Z it>0.0;
  • if TR i='S', Z it≥0.0, for i=1,2,…,k and t=1,2,…,n.
4:   KMAX – INTEGERInput
On entry: the first dimension of the arrays Z, DELTA, QQ, V, PREDZ and SEFZ as declared in the (sub)program from which G13DJF is called.
Constraint: KMAX≥K.
5:   TR K – CHARACTER(1) arrayInput
On entry: TR i indicates whether the ith time series is to be transformed, for i=1,2,…,k.
TR i='N'
No transformation is used.
TR i='L'
A log transformation is used.
TR i='S'
A square root transformation is used.
Constraint: TR i='N', 'L' or 'S', for i=1,2,…,k.
6:   ID K – INTEGER arrayInput
On entry: ID i must specify, di, the order of differencing required for the ith series.
Constraint: 0≤ID i<N-max IP,IQ, for i=1,2,…,k.
7:   DELTA KMAX* – REAL (KIND=nag_wp) arrayInput
Note: the second dimension of the array DELTA must be at least max 1,d, where d=max ID i.
On entry: if ID i>0, then DELTA ij must be set equal to δ ij, for j=1,2,…,di and i=1,2,…,k.
If d=0, DELTA is not referenced.
8:   IP – INTEGERInput
On entry: p, the number of AR parameter matrices.
Constraint: IP≥0.
9:   IQ – INTEGERInput
On entry: q, the number of MA parameter matrices.
Constraint: IQ≥0.
10:   MEAN – CHARACTER(1)Input
On entry: MEAN='M', if components of μ have been estimated and MEAN='Z', if all elements of μ are to be taken as zero.
Constraint: MEAN='M' or 'Z'.
11:   PAR LPAR – REAL (KIND=nag_wp) arrayInput
On entry: must contain the parameter estimates read in row by row in the order ϕ 1,ϕ 2,…,ϕp, θ 1,θ 2,…,θq, μ.
Thus,
  • if IP>0, PAR l-1×k×k+i-1×k+j must be set equal to an estimate of the i,jth element of ϕl, for l=1,2,…,p, i=1,2,…,k and j=1,2,…,k;
  • if IQ>0, PAR p×k×k+l-1×k×k+i-1×k+j must be set equal to an estimate of the i,jth element of θl, for l=1,2,…,q, i=1,2,…,k and j=1,2,…,k;
  • if MEAN='M', PAR p+q×k×k+i must be set equal to an estimate of the ith component of μ, for i=1,2,…,k.
Constraint: the first IP×K×K elements of PAR must satisfy the stationarity condition and the next IQ×K×K elements of PAR must satisfy the invertibility condition.
12:   LPAR – INTEGERInput
On entry: the dimension of the array PAR as declared in the (sub)program from which G13DJF is called.
Constraints:
  • if MEAN='Z', LPAR≥max 1,IP+IQ×K×K;
  • if MEAN='M', LPAR≥IP+IQ×K×K+K.
13:   QQ KMAXK – REAL (KIND=nag_wp) arrayInput/Output
On entry: QQ ij must contain an estimate of the i,jth element of Σ. The lower triangle only is needed.
Constraint: QQ must be positive definite.
On exit: if IFAIL≠1, then the upper triangle is set equal to the lower triangle.
14:   V KMAX* – REAL (KIND=nag_wp) arrayInput
Note: the second dimension of the array V must be at least max 1,N-d, where d=max ID i.
On entry: V it must contain an estimate of the ith component of ε t+d, for i=1,2,…,k and t=1,2,…,n-d.
If q=0, V is not used.
15:   LMAX – INTEGERInput
On entry: the number, lmax, of forecasts required.
Constraint: LMAX≥1.
16:   PREDZ KMAXLMAX – REAL (KIND=nag_wp) arrayOutput
On exit: PREDZ il contains the forecast of z i,n+l, for i=1,2,…,k and l=1,2,…,lmax.
17:   SEFZ KMAXLMAX – REAL (KIND=nag_wp) arrayOutput
On exit: SEFZ il contains an estimate of the standard error of the forecast of z i,n+l, for i=1,2,…,k and l=1,2,…,lmax.
18:   REF LREF – REAL (KIND=nag_wp) arrayOutput
On exit: the reference vector which may be used to update forecasts using G13DKF. The first LMAX-1×K×K elements contain the ψ weight matrices, ψ 1,ψ 2,…,ψ lmax-1. The next K×LMAX elements contain the forecasts of the transformed series Z^n+1*,Z^n+2*,…, Z^n+lmax* and the next K×LMAX contain the variances of the forecasts of the transformed variables. The last K elements are used to store the transformations for the series.
19:   LREF – INTEGERInput
On entry: the dimension of the array REF as declared in the (sub)program from which G13DJF is called.
Constraint: LREF≥LMAX-1×K×K+2×K×LMAX+K.
20:   WORK LWORK – REAL (KIND=nag_wp) arrayWorkspace
21:   LWORK – INTEGERInput
On entry: the dimension of the array WORK as declared in the (sub)program from which G13DJF is called.
Constraint: if r=max IP,IQ and d=max ID i, for i=1,2,…,k, LWORK≥max Kr Kr+2, IP+d+2 K 2+N+LMAX K.
22:   IWORK LIWORK – INTEGER arrayWorkspace
23:   LIWORK – INTEGERInput
On entry: the dimension of the array IWORK as declared in the (sub)program from which G13DJF is called.
Constraint: LIWORK≥K×max IP,IQ.
24:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | K<1,
or | N<3,
or | KMAX<K,
or | ID i<0 for some i=1,2,…,k,
or | ID i≥N-max IP,IQ for some i=1,2,…,k,
or | IP<0,
or | IQ<0,
or | MEAN≠'M' or 'Z',
or | LPAR<IP+IQ×K×K+K, and MEAN='M',
or | LPAR<IP+IQ×K×K and MEAN='Z',
or | N×K≤IP+IQ×K×K+K+K K+1/2, and MEAN='M',
or | N×K≤IP+IQ×K×K+K K+1/2 and MEAN='Z',
or | LMAX<1,
or | LREF<LMAX-1×K×K+2×K×LMAX+K,
or | LWORK is too small,
or | LIWORK is too small.
IFAIL=2
On entry, at least one of the first k elements of TR is not equal to 'N', 'L' or 'S'.
IFAIL=3
On entry, one or more of the transformations requested cannot be computed; that is, you may be trying to log or square-root a series, some of whose values are negative.
IFAIL=4
On entry, either QQ is not positive definite or the autoregressive parameter matrices are extremely close to or outside the stationarity region, or the moving average parameter matrices are extremely close to or outside the invertibility region. To proceed, you must supply different parameter estimates in the arrays PAR and QQ.
IFAIL=5
This is an unlikely exit brought about by an excessive number of iterations being needed to evaluate the eigenvalues of the matrices required to check for stationarity and invertibility; see G13DXF. All output arguments are undefined.
IFAIL=6
This is an unlikely exit which could occur if QQ is nearly non positive definite. In this case the standard deviations of the forecast errors may be non-positive. To proceed, you must supply different parameter estimates in the array QQ.
IFAIL=7
This is an unlikely exit. For one of the series, overflow will occur if the forecasts are computed. You should check whether the transformations requested in the array TR are sensible. All output arguments are undefined.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The matrix computations are believed to be stable.

8 Parallelism and Performance

G13DJF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13DJF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

The same differencing operator does not have to be applied to all the series. For example, suppose we have k=2, and wish to apply the second order differencing operator ∇2 to the first series and the first-order differencing operator ∇ to the second series:
w 1 t=∇2 z 1 t= 1-B 2 z 1 t=1-2 B+B 2 Z 1 t,   and w 2 t=∇z 2 t=1-B z 2 t.
Then d 1=2,d 2=1, d=max d 1,d 2=2, and
DELTA= δ 11 δ 12 δ 21 = 2 -1 1 .
Note: although differencing may already have been applied prior to the model fitting stage, the differencing parameters supplied in DELTA are part of the model definition and are still required by this routine to produce the forecasts.
G13DJF should not be used when the moving average parameters lie close to the boundary of the invertibility region. The routine does test for both invertibility and stationarity but if in doubt, you may use G13DXF, before calling this routine, to check that the VARMA model being used is invertible.
On a successful exit, the quantities K, LMAX, KMAX, REF and LREF will be suitable for input to G13DKF.

10 Example

This example computes forecasts of the next five values in two series each of length 48. No transformation is to be used and no differencing is to be applied to either of the series. G13DDF is first called to fit an AR(1) model to the series. The mean vector μ is to be estimated and ϕ 1 2,1 constrained to be zero.

10.1 Program Text

Program Text (g13djfe.f90)

10.2 Program Data

Program Data (g13djfe.d)

10.3 Program Results

Program Results (g13djfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13DKF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13DKF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13DKF accepts a sequence of new observations in a multivariate time series and updates both the forecasts and the standard deviations of the forecast errors. A call to G13DJF must be made prior to calling this routine in order to calculate the elements of a reference vector together with a set of forecasts and their standard errors. On a successful exit from G13DKF the reference vector is updated so that should future series values become available these forecasts may be updated by recalling G13DKF.

2 Specification

SUBROUTINE G13DKF ( K, LMAX, M, MLAST, Z, KMAX, REF, LREF, V, PREDZ, SEFZ, WORK, IFAIL)
INTEGER | K, LMAX, M, MLAST, KMAX, LREF, IFAIL
REAL (KIND=nag_wp) | Z(KMAX,M), REF(LREF), V(KMAX,M), PREDZ(KMAX,LMAX), SEFZ(KMAX,LMAX), WORK(K*M)

3 Description

Let Zt = z 1 t,z 2 t,…,z kt T , for t=1,2,…,n, denote a k-dimensional time series for which forecasts of Z^n+1,Z^n+2,…, Z^n+lmax have been computed using G13DJF. Given m further observations Z n+1,Z n+2,…,Z n+m, where m<lmax, G13DKF updates the forecasts of Z n+m+1,Z n+m+2,…,Z n+lmax and their corresponding standard errors.
G13DKF uses a multivariate version of the procedure described in Box and Jenkins (1976). The forecasts are updated using the ψ weights, computed in G13DJF. If Zt* denotes the transformed value of Zt and Z^t*l denotes the forecast of Z t+l* from time t with a lead of l (that is the forecast of Z t+l* given observations Zt*,Z t-1*,…), then
Z^t+1*l=τ+ψlε t+1+ψ l+1εt+ψ l+2ε t-1+⋯
and
Z^t*l+ 1=τ+ψ l+ 1εt+ψ l+ 2ε t- 1+⋯
where τ is a constant vector of length k involving the differencing parameters and the mean vector μ. By subtraction we obtain
Z^t+1*l=Z^t*l+1+ψlε t+1.
Estimates of the residuals corresponding to the new observations are also computed as ε n+l=Z n+l*-Z^n*l, for l=1,2,…,m. These may be of use in checking that the new observations conform to the previously fitted model.
On a successful exit, the reference array is updated so that G13DKF may be called again should future series values become available, see Section 9.
When a transformation has been used the forecasts and their standard errors are suitably modified to give results in terms of the original series Zt; see Granger and Newbold (1976).

4 References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day
Granger C W J and Newbold P (1976) Forecasting transformed series J. Roy. Statist. Soc. Ser. B 38 189–203
Wei W W S (1990) Time Series Analysis: Univariate and Multivariate Methods Addison–Wesley

5 Arguments

The quantities K, LMAX, KMAX, REF and LREF from G13DJF are suitable for input to G13DKF.
1:   K – INTEGERInput
On entry: k, the dimension of the multivariate time series.
Constraint: K≥1.
2:   LMAX – INTEGERInput
On entry: the number, lmax, of forecasts requested in the call to G13DJF.
Constraint: LMAX≥2.
3:   M – INTEGERInput
On entry: m, the number of new observations available since the last call to either G13DJF or G13DKF. The number of new observations since the last call to G13DJF is then M+MLAST.
Constraint: 0<M<LMAX-MLAST.
4:   MLAST – INTEGERInput/Output
On entry: on the first call to G13DKF, since calling G13DJF, MLAST must be set to 0 to indicate that no new observations have yet been used to update the forecasts; on subsequent calls MLAST must contain the value of MLAST as output on the previous call to G13DKF.
On exit: is incremented by m to indicate that MLAST+M observations have now been used to update the forecasts since the last call to G13DJF.
MLAST must not be changed between calls to G13DKF, unless a call to G13DJF has been made between the calls in which case MLAST should be reset to 0.
Constraint: 0≤MLAST<LMAX-M.
5:   Z KMAXM – REAL (KIND=nag_wp) arrayInput
On entry: Z ij must contain the value of z i,n+MLAST+j, for i=1,2,…,k and j=1,2,…,m, and where n is the number of observations in the time series in the last call made to G13DJF.
Constraint: if the transformation defined in TR in G13DJF for the ith series is the log transformation, then Z ij>0.0, and if it is the square-root transformation, then Z ij≥0.0, for j=1,2,…,m and i=1,2,…,k.
6:   KMAX – INTEGERInput
On entry: the first dimension of the arrays Z, PREDZ, SEFZ and V as declared in the (sub)program from which G13DKF is called.
Constraint: KMAX≥K.
7:   REF LREF – REAL (KIND=nag_wp) arrayInput/Output
On entry: must contain the first LMAX-1×K×K+2×K×LMAX+K elements of the reference vector as returned on a successful exit from G13DJF (or a previous call to G13DKF).
On exit: the elements of REF are updated. The first LMAX-1×K×K elements store the ψ weights ψ 1,ψ 2,…,ψ lmax-1. The next K×LMAX elements contain the forecasts of the transformed series and the next K×LMAX elements contain the variances of the forecasts of the transformed variables; see G13DJF. The last K elements are not updated.
8:   LREF – INTEGERInput
On entry: the dimension of the array REF as declared in the (sub)program from which G13DKF is called.
Constraint: LREF≥LMAX-1×K×K+2×K×LMAX+K.
9:   V KMAXM – REAL (KIND=nag_wp) arrayOutput
On exit: V ij contains an estimate of the ith component of ε n+MLAST+j, for i=1,2,…,k and j=1,2,…,m.
10:   PREDZ KMAXLMAX – REAL (KIND=nag_wp) arrayInput/Output
On entry: nonupdated values are kept intact.
On exit: PREDZ ij contains the updated forecast of z i,n+j, for i=1,2,…,k and j=MLAST+M+1,…,lmax.
The columns of PREDZ corresponding to the new observations since the last call to either G13DJF or G13DKF are set equal to the corresponding columns of Z.
11:   SEFZ KMAXLMAX – REAL (KIND=nag_wp) arrayInput/Output
On entry: nonupdated values are kept intact.
On exit: SEFZ ij contains an estimate of the standard error of the corresponding element of PREDZ, for i=1,2,…,k and j=MLAST+M+1,…,lmax.
The columns of SEFZ corresponding to the new observations since the last call to either G13DJF or G13DKF are set equal to zero.
12:   WORK K×M – REAL (KIND=nag_wp) arrayWorkspace
13:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | K<1,
or | LMAX<2,
or | M≤0,
or | MLAST+M≥LMAX,
or | MLAST<0,
or | KMAX<K,
or | LREF<LMAX-1×K×K+2×K×LMAX+K.
IFAIL=2
On entry, some of the elements of the reference vector, REF, have been corrupted since the most recent call to G13DJF (or G13DKF).
IFAIL=3
On entry, one or more of the elements of Z is invalid, for the transformation being used; that is you may be trying to log or square root a series, some of whose values are negative.
IFAIL=4
This is an unlikely exit. For one of the series, overflow will occur if the forecasts are updated. You should check whether the elements of REF have been corrupted.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The matrix computations are believed to be stable.

8 Parallelism and Performance

G13DKF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

If a further m* observations, Z n+MLAST+1,Z n+MLAST+2,…, Z n+MLAST+m*, become available, then forecasts of Z n+MLAST+m*+1,Z n+MLAST+m*+2,…, Z n+lmax may be updated by recalling G13DKF with M=m*. Note that M and the contents of the array Z are the only quantities which need updating; MLAST is updated on exit from the previous call. On a successful exit, V contains estimates of ε n+MLAST+1,ε n+MLAST+2,…, ε n+MLAST+m*; columns MLAST+1,MLAST+2,…,MLAST+m* of PREDZ contain the new observed values Z n+MLAST+1,Z n+MLAST+2,…, Z n+MLAST+m* and columns MLAST+1,MLAST+2,…,MLAST+m* of SEFZ are set to zero.

10 Example

This example shows how to update the forecasts of two series each of length 48. No transformation has been used and no differencing applied to either of the series. G13DDF is first called to fit an AR(1) model to the series. μ is to be estimated and ϕ 1 2,1 constrained to be zero. A call to G13DJF is then made in order to compute forecasts of the next five series values. After one new observation becomes available the four forecasts are updated. A further observation becomes available and the three forecasts are updated.

10.1 Program Text

Program Text (g13dkfe.f90)

10.2 Program Data

Program Data (g13dkfe.d)

10.3 Program Results

Program Results (g13dkfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13DLF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13DLF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13DLF differences and/or transforms a multivariate time series. It is intended to be used prior to G13DDF to fit a vector autoregressive moving average (VARMA) model to the differenced/transformed series.

2 Specification

SUBROUTINE G13DLF ( K, N, Z, KMAX, TR, ID, DELTA, W, ND, WORK, IFAIL)
INTEGER | K, N, KMAX, ID(K), ND, IFAIL
REAL (KIND=nag_wp) | Z(KMAX,N), DELTA(KMAX,*), W(KMAX,*), WORK(K*N)
CHARACTER(1) | TR(K)

3 Description

For certain time series it may first be necessary to difference the original data to obtain a stationary series before calculating autocorrelations, etc. This routine also allows you to apply either a square root or a log transformation to the original time series to stabilize the variance if required.
If the order of differencing required for the ith series is di, then the differencing operator is defined by δi B=1-δ i 1 B-δ i 2 B 2-⋯-δ i di B di, where B is the backward shift operator; that is, B Zt=Z t-1. Let d denote the maximum of the orders of differencing, di, over the k series. The routine computes values of the differenced/transformed series Wt = w 1 t,w 2 t,…,w kt T , for t=d+1,…,n, as follows:
w it=δi B z it*,  i=1,2,…,k
where z it* are the transformed values of the original k-dimensional time series Zt = z 1 t,z 2 t,…,z kt T .
The differencing parameters δ ij, for i=1,2,…,k and j=1,2,…,di, must be supplied by you. If the ith series does not require differencing, then di=0.

4 References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day
Wei W W S (1990) Time Series Analysis: Univariate and Multivariate Methods Addison–Wesley

5 Arguments

1:   K – INTEGERInput
On entry: k, the dimension of the multivariate time series.
Constraint: K≥1.
2:   N – INTEGERInput
On entry: n, the number of observations in the series, prior to differencing.
Constraint: N≥1.
3:   Z KMAXN – REAL (KIND=nag_wp) arrayInput
On entry: Z it must contain, z it, the ith component of Zt, for i=1,2,…,k and t=1,2,…,n.
Constraints:
  • if TR i='L', Z it>0.0;
  • if TR i='S', Z it≥0.0, for i=1,2,…,k and t=1,2,…,n.
4:   KMAX – INTEGERInput
On entry: the first dimension of the arrays Z, DELTA and W as declared in the (sub)program from which G13DLF is called.
Constraint: KMAX≥K.
5:   TR K – CHARACTER(1) arrayInput
On entry: TR i indicates whether the ith time series is to be transformed, for i=1,2,…,k.
TR i='N'
No transformation is used.
TR i='L'
A log transformation is used.
TR i='S'
A square root transformation is used.
Constraint: TR i='N', 'L' or 'S', for i=1,2,…,k.
6:   ID K – INTEGER arrayInput
On entry: the order of differencing for each series, d 1,d 2,…,dk.
Constraint: 0≤ID i<N, for i=1,2,…,K.
7:   DELTA KMAX* – REAL (KIND=nag_wp) arrayInput
Note: the second dimension of the array DELTA must be at least max 1,d, where d=max ID i.
On entry: if ID i>0, then DELTA ij must be set equal to δ ij, for j=1,2,…,di and i=1,2,…,k.
If d=0, then DELTA is not referenced.
8:   W KMAX* – REAL (KIND=nag_wp) arrayOutput
Note: the second dimension of the array W must be at least N-d, where d=max ID i.
On exit: W it contains the value of w i,t+d, for i=1,2,…,k and t=1,2,…,n-d.
9:   ND – INTEGEROutput
On exit: the number of differenced values, n-d, in the series, where d=max ID i.
10:   WORK K×N – REAL (KIND=nag_wp) arrayWorkspace
11:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | K<1,
or | N<1,
or | KMAX<K.
IFAIL=2
On entry, | ID i<0, for some i=1,2,…,k,
or | ID i≥N, for some i=1,2,…,k.
IFAIL=3
On entry, at least one of the first k elements of TR is not equal to 'N', 'L' or 'S'.
IFAIL=4
On entry, one or more of the elements of Z is invalid, for the transformation requested; that is, you may be trying to log or square root a series, some of whose values are negative.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The computations are believed to be stable.

8 Parallelism and Performance

G13DLF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

The same differencing operator does not have to be applied to all the series. For example, suppose we have k=2, and wish to apply the second-order differencing operator ∇2 to the first series and the first-order differencing operator ∇ to the second series:
w 1 t =∇2 z 1 t= 1-B 2 z 1 t=1-2 B+B 2 z 1 t,   and w 2 t =∇z 2 t=1-B z 2 t.
Then d 1=2,d 2=1, d=max d 1,d 2=2, and
DELTA = δ 11 δ 12 δ 21 = 2 -1 1 .

10 Example

A program to difference (non-seasonally) each of two time series of length 48. No transformation is to be applied to either of the series.

10.1 Program Text

Program Text (g13dlfe.f90)

10.2 Program Data

Program Data (g13dlfe.d)

10.3 Program Results

Program Results (g13dlfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13DMF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13DMF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13DMF calculates the sample cross-correlation (or cross-covariance) matrices of a multivariate time series.

2 Specification

SUBROUTINE G13DMF ( MATRIX, K, N, M, W, KMAX, WMEAN, R0, R, IFAIL)
INTEGER | K, N, M, KMAX, IFAIL
REAL (KIND=nag_wp) | W(KMAX,N), WMEAN(K), R0(KMAX,K), R(KMAX,KMAX,M)
CHARACTER(1) | MATRIX

3 Description

Let Wt = w 1 t,w 2 t,…,w kt T , for t=1,2,…,n, denote n observations of a vector of k time series. The sample cross-covariance matrix at lag l is defined to be the k by k matrix C^l, whose (i,j)th element is given by
C^ij l=1 n∑t=l+1 n w i t-l-w-iw jt-w-j,  l=0,1,2,…,m, ​i=1,2,…,k​ and ​j=1,2,…,k,
where w-i and w-j denote the sample means for the ith and jth series respectively. The sample cross-correlation matrix at lag l is defined to be the k by k matrix R^l, whose i,jth element is given by
R^ ij l = C^ ij l C^ ii 0 C^ jj 0 ,   l=0,1,2,…,m , ​ i=1,2,…,k ​ and ​ j=1,2,…,k .
The number of lags, m, is usually taken to be at most n/4.
If Wt follows a vector moving average model of order q, then it can be shown that the theoretical cross-correlation matrices R l are zero beyond lag q. In order to help spot a possible cut-off point, the elements of R^l are usually compared to their approximate standard error of 1/n. For further details see, for example, Wei (1990).
The routine uses a single pass through the data to compute the means and the cross-covariance matrix at lag zero. The cross-covariance matrices at further lags are then computed on a second pass through the data.

4 References

Wei W W S (1990) Time Series Analysis: Univariate and Multivariate Methods Addison–Wesley
West D H D (1979) Updating mean and variance estimates: An improved method Comm. ACM 22 532–555

5 Arguments

1:   MATRIX – CHARACTER(1)Input
On entry: indicates whether the cross-covariance or cross-correlation matrices are to be computed.
MATRIX='V'
The cross-covariance matrices are computed.
MATRIX='R'
The cross-correlation matrices are computed.
Constraint: MATRIX='V' or 'R'.
2:   K – INTEGERInput
On entry: k, the dimension of the multivariate time series.
Constraint: K≥1.
3:   N – INTEGERInput
On entry: n, the number of observations in the series.
Constraint: N≥2.
4:   M – INTEGERInput
On entry: m, the number of cross-correlation (or cross-covariance) matrices to be computed. If in doubt set M=10. However it should be noted that M is usually taken to be at most N/4.
Constraint: 1≤M<N.
5:   W KMAXN – REAL (KIND=nag_wp) arrayInput
On entry: W it must contain the observation w it, for i=1,2,…,k and t=1,2,…,n.
6:   KMAX – INTEGERInput
On entry: the first dimension of the arrays W, R0 and R and the second dimension of the array R as declared in the (sub)program from which G13DMF is called.
Constraint: KMAX≥K.
7:   WMEAN K – REAL (KIND=nag_wp) arrayOutput
On exit: the means, w-i, for i=1,2,…,k.
8:   R0 KMAXK – REAL (KIND=nag_wp) arrayOutput
On exit: if i≠j, then R0 ij contains an estimate of the i,jth element of the cross-correlation (or cross-covariance) matrix at lag zero, R^ij 0; if i=j, then if MATRIX='V', R0 ii contains the variance of the ith series, C^ii 0, and if MATRIX='R', R0 ii contains the standard deviation of the ith series, C^ii 0.
If IFAIL=2 and MATRIX='R', then on exit all the elements in R0 whose computation involves the zero variance are set to zero.
9:   R KMAXKMAXM – REAL (KIND=nag_wp) arrayOutput
On exit: R ijl contains an estimate of the (i,j)th element of the cross-correlation (or cross-covariance) at lag l, R^ij l, for l=1,2,…,m, i=1,2,…,k and j=1,2,…,k.
If IFAIL=2 and MATRIX='R', then on exit all the elements in R whose computation involves the zero variance are set to zero.
10:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | MATRIX≠'V' or 'R',
or | K<1,
or | N<2,
or | M<1,
or | M≥N,
or | KMAX<K.
IFAIL=2
On entry, at least one of the k series is such that all its elements are practically equal giving zero (or near zero) variance. In this case if MATRIX='R' all the correlations in R0 and R involving this variance are set to zero.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

For a discussion of the accuracy of the one-pass algorithm used to compute the sample cross-covariances at lag zero see West (1979). For the other lags a two-pass algorithm is used to compute the cross-covariances; the accuracy of this algorithm is also discussed in West (1979). The accuracy of the cross-correlations will depend on the accuracy of the computed cross-covariances.

8 Parallelism and Performance

G13DMF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

The time taken is roughly proportional to mn k 2.

10 Example

This program computes the sample cross-correlation matrices of two time series of length 48, up to lag 10. It also prints the cross-correlation matrices together with plots of symbols indicating which elements of the correlation matrices are significant. Three * represent significance at the 0.5% level, two * represent significance at the 1% level and a single * represents significance at the 5% level. The * are plotted above or below the line depending on whether the elements are significant in the positive or negative direction.

10.1 Program Text

Program Text (g13dmfe.f90)

10.2 Program Data

Program Data (g13dmfe.d)

10.3 Program Results

Program Results (g13dmfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13DNF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13DNF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13DNF calculates the sample partial lag correlation matrices of a multivariate time series. A set of χ 2-statistics and their significance levels are also returned. A call to G13DMF is usually made prior to calling this routine in order to calculate the sample cross-correlation matrices.

2 Specification

SUBROUTINE G13DNF ( K, N, M, KMAX, R0, R, MAXLAG, PARLAG, X, PVALUE, WORK, LWORK, IFAIL)
INTEGER | K, N, M, KMAX, MAXLAG, LWORK, IFAIL
REAL (KIND=nag_wp) | R0(KMAX,K), R(KMAX,KMAX,M), PARLAG(KMAX,KMAX,M), X(M), PVALUE(M), WORK(LWORK)

3 Description

Let Wt = w 1 t,w 2 t,…,w kt T , for t=1,2,…,n, denote n observations of a vector of k time series. The partial lag correlation matrix at lag l, P l, is defined to be the correlation matrix between Wt and W t+l, after removing the linear dependence on each of the intervening vectors W t+1,W t+2,…,W t+l-1. It is the correlation matrix between the residual vectors resulting from the regression of W t+l on the carriers W t+l-1,…,W t+1 and the regression of Wt on the same set of carriers; see Heyse and Wei (1985).
P l has the following properties.
(i) | If Wt follows a vector autoregressive model of order p, then P l=0 for l>p;
(ii) | When k=1, P l reduces to the univariate partial autocorrelation at lag l;
(iii) | Each element of P l is a properly normalized correlation coefficient;
(iv) | When l=1, P l is equal to the cross-correlation matrix at lag 1 (a natural property which also holds for the univariate partial autocorrelation function).
Sample estimates of the partial lag correlation matrices may be obtained using the recursive algorithm described in Wei (1990). They are calculated up to lag m, which is usually taken to be at most n/4. Only the sample cross-correlation matrices (R^l, for l=0,1,…,m) and the standard deviations of the series are required as input to G13DNF. These may be computed by G13DMF. Under the hypothesis that Wt follows an autoregressive model of order s-1, the elements of the sample partial lag matrix P^s, denoted by P^ij s, are asymptotically Normally distributed with mean zero and variance 1/n. In addition the statistic
X s=n∑i=1 k∑j=1 k P^ij s 2
has an asymptotic χ 2-distribution with k 2 degrees of freedom. These quantities, X l, are useful as a diagnostic aid for determining whether the series follows an autoregressive model and, if so, of what order.

4 References

Heyse J F and Wei W W S (1985) The partial lag autocorrelation function Technical Report No. 32 Department of Statistics, Temple University, Philadelphia
Wei W W S (1990) Time Series Analysis: Univariate and Multivariate Methods Addison–Wesley

5 Arguments

1:   K – INTEGERInput
On entry: k, the dimension of the multivariate time series.
Constraint: K≥1.
2:   N – INTEGERInput
On entry: n, the number of observations in each series.
Constraint: N≥2.
3:   M – INTEGERInput
On entry: m, the number of partial lag correlation matrices to be computed. Note this also specifies the number of sample cross-correlation matrices that must be contained in the array R.
Constraint: 1≤M<N.
4:   KMAX – INTEGERInput
On entry: the first dimension of the arrays R0, R and PARLAG and the second dimension of the arrays R and PARLAG as declared in the (sub)program from which G13DNF is called.
Constraint: KMAX≥K.
5:   R0 KMAXK – REAL (KIND=nag_wp) arrayInput
On entry: if i≠j, then R0 ij must contain the i,jth element of the sample cross-correlation matrix at lag zero, R^ij 0. If i=j, then R0 ii must contain the standard deviation of the ith series.
6:   R KMAXKMAXM – REAL (KIND=nag_wp) arrayInput
On entry: R ijl must contain the i,jth element of the sample cross-correlation at lag l, R^ij l, for l=1,2,…,m, i=1,2,…,k and j=1,2,…,k, where series j leads series i (see Section 9).
7:   MAXLAG – INTEGEROutput
On exit: the maximum lag up to which partial lag correlation matrices (along with χ 2-statistics and their significance levels) have been successfully computed. On a successful exit MAXLAG will equal M. If IFAIL=2 on exit, then MAXLAG will be less than M.
8:   PARLAG KMAXKMAXM – REAL (KIND=nag_wp) arrayOutput
On exit: PARLAG ijl contains the i,jth element of the sample partial lag correlation matrix at lag l, P^ij l, for l=1,2,…,MAXLAG, i=1,2,…,k and j=1,2,…,k.
9:   X M – REAL (KIND=nag_wp) arrayOutput
On exit: X l contains the χ 2-statistic at lag l, for l=1,2,…,MAXLAG.
10:   PVALUE M – REAL (KIND=nag_wp) arrayOutput
On exit: PVALUE l contains the significance level of the corresponding χ 2-statistic in X, for l=1,2,…,MAXLAG.
11:   WORK LWORK – REAL (KIND=nag_wp) arrayWorkspace
12:   LWORK – INTEGERInput
On entry: the dimension of the array WORK as declared in the (sub)program from which G13DNF is called.
Constraint: LWORK≥5⁢M+6⁢K 2+K.
13:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | K<1,
or | N<2,
or | M<1,
or | M≥N,
or | KMAX<K,
or | LWORK<5⁢M+6 K 2+K.
IFAIL=2
The recursive equations used to compute the sample partial lag correlation matrices have broken down at lag MAXLAG+1. All output quantities in the arrays PARLAG, X and PVALUE up to and including lag MAXLAG will be correct.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The accuracy will depend upon the accuracy of the sample cross-correlations.

8 Parallelism and Performance

G13DNF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13DNF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

The time taken is roughly proportional to m 2k 3.
If you have calculated the sample cross-correlation matrices in the arrays R0 and R, without calling G13DMF, then care must be taken to ensure they are supplied as described in Section 5. In particular, for l≥1, R^ij l must contain the sample cross-correlation coefficient between w i t-l and w jt.
The routine G13DBF computes squared partial autocorrelations for a specified number of lags. It may also be used to estimate a sequence of partial autoregression matrices at lags 1,2,… by making repeated calls to the routine with the argument NK set to 1,2,…. The i,jth element of the sample partial autoregression matrix at lag l is given by W i,j,l when NK is set equal to l on entry to G13DBF. Note that this is the ‘Yule–Walker’ estimate. Unlike the partial lag correlation matrices computed by G13DNF, when Wt follows an autoregressive model of order s-1, the elements of the sample partial autoregressive matrix at lag s do not have variance 1/n, making it very difficult to spot a possible cut-off point. The differences between these matrices are discussed further by Wei (1990).
Note that G13DBF takes the sample cross-covariance matrices as input whereas this routine requires the sample cross-correlation matrices to be input.

10 Example

This example computes the sample partial lag correlation matrices of two time series of length 48, up to lag 10. The matrices, their χ 2-statistics and significance levels and a plot of symbols indicating which elements of the sample partial lag correlation matrices are significant are printed. Three * represent significance at the 0.5% level, two * represent significance at the 1% level and a single * represents significance at the 5% level. The * are plotted above or below the central line depending on whether the elements are significant in a positive or negative direction.

10.1 Program Text

Program Text (g13dnfe.f90)

10.2 Program Data

Program Data (g13dnfe.d)

10.3 Program Results

Program Results (g13dnfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13DPF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13DPF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13DPF calculates the sample partial autoregression matrices of a multivariate time series. A set of likelihood ratio statistics and their significance levels are also returned. These quantities are useful for determining whether the series follows an autoregressive model and, if so, of what order.

2 Specification

SUBROUTINE G13DPF ( K, N, Z, KMAX, M, MAXLAG, PARLAG, SE, QQ, X, PVALUE, LOGLHD, WORK, LWORK, IWORK, IFAIL)
INTEGER | K, N, KMAX, M, MAXLAG, LWORK, IWORK(K*M), IFAIL
REAL (KIND=nag_wp) | Z(KMAX,N), PARLAG(KMAX,KMAX,M), SE(KMAX,KMAX,M), QQ(KMAX,KMAX,M), X(M), PVALUE(M), LOGLHD(M), WORK(LWORK)

3 Description

Let Wt = w 1 t,w 2 t,…,w kt T , for t=1,2,…,n, denote a vector of k time series. The partial autoregression matrix at lag l, Pl, is defined to be the last matrix coefficient when a vector autoregressive model of order l is fitted to the series. Pl has the property that if Wt follows a vector autoregressive model of order p then Pl=0 for l>p.
Sample estimates of the partial autoregression matrices may be obtained by fitting autoregressive models of successively higher orders by multivariate least squares; see Tiao and Box (1981) and Wei (1990). These models are fitted using a QR algorithm based on the routines G02DCF and G02DFF. They are calculated up to lag m, which is usually taken to be at most n/4.
The routine also returns the asymptotic standard errors of the elements of P^l and an estimate of the residual variance-covariance matrix Σ^l, for l=1,2,…,m. If Sl denotes the residual sum of squares and cross-products matrix after fitting an AR l model to the series then under the null hypothesis H 0:Pl=0 the test statistic
Xl= - n-m-1 -12-lk log Sl S l-1
is asymptotically distributed as χ 2 with k 2 degrees of freedom. Xl provides a useful diagnostic aid in determining the order of an autoregressive model. (Note that Σ^l=Sl/n-l.) The routine also returns an estimate of the maximum of the log-likelihood function for each AR model that has been fitted.

4 References

Tiao G C and Box G E P (1981) Modelling multiple time series with applications J. Am. Stat. Assoc. 76 802–816
Wei W W S (1990) Time Series Analysis: Univariate and Multivariate Methods Addison–Wesley

5 Arguments

1:   K – INTEGERInput
On entry: k, the number of time series.
Constraint: K≥1.
2:   N – INTEGERInput
On entry: n, the number of observations in the time series.
Constraint: N≥4.
3:   Z KMAXN – REAL (KIND=nag_wp) arrayInput
On entry: Z it must contain the observation w it, for i=1,2,…,k and t=1,2,…,n.
4:   KMAX – INTEGERInput
On entry: the first dimension of the arrays Z, PARLAG, SE and QQ and the second dimension of the arrays PARLAG, SE and QQ as declared in the (sub)program from which G13DPF is called.
Constraint: KMAX≥K.
5:   M – INTEGERInput
On entry: m, the number of partial autoregression matrices to be computed. If in doubt set M=10.
Constraint: M≥1 and N-M-K×M+1≥K.
6:   MAXLAG – INTEGEROutput
On exit: the maximum lag up to which partial autoregression matrices (along with their likelihood ratio statistics and their significance levels) have been successfully computed. On a successful exit MAXLAG will equal M. If IFAIL=2 on exit then MAXLAG will be less than M.
7:   PARLAG KMAXKMAXM – REAL (KIND=nag_wp) arrayOutput
On exit: PARLAG ijl contains an estimate of the i,jth element of the partial autoregression matrix at lag l, P^l ij, for l=1,2,…,MAXLAG, i=1,2,…,k and j=1,2,…,k.
8:   SE KMAXKMAXM – REAL (KIND=nag_wp) arrayOutput
On exit: SE ijl contains an estimate of the standard error of the corresponding element in the array PARLAG.
9:   QQ KMAXKMAXM – REAL (KIND=nag_wp) arrayOutput
On exit: QQ ijl contains an estimate of the i,jth element of the corresponding variance-covariance matrix Σ^l, for l=1,2,…,MAXLAG, i=1,2,…,k and j=1,2,…,k.
10:   X M – REAL (KIND=nag_wp) arrayOutput
On exit: X l contains Xl, the likelihood ratio statistic at lag l, for l=1,2,…,MAXLAG.
11:   PVALUE M – REAL (KIND=nag_wp) arrayOutput
On exit: PVALUE l contains the significance level of the statistic in the corresponding element of X.
12:   LOGLHD M – REAL (KIND=nag_wp) arrayOutput
On exit: LOGLHD l contains an estimate of the maximum of the log-likelihood function when an AR l model has been fitted to the series, for l=1,2,…,MAXLAG.
13:   WORK LWORK – REAL (KIND=nag_wp) arrayWorkspace
14:   LWORK – INTEGERInput
On entry: the dimension of the array WORK as declared in the (sub)program from which G13DPF is called.
Constraint: LWORK≥k+1⁢k+l⁢4+k+2⁢l 2, where l=mk+1.
15:   IWORK K×M – INTEGER arrayWorkspace
16:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | K<1,
or | N<4,
or | KMAX<K,
or | M<1,
or | N-M-K×M+1<K,
or | LWORK is too small.
IFAIL=2
The recursive equations used to compute the sample partial autoregression matrices have broken down at lag MAXLAG+1. This exit could occur if the regression model is overparameterised. For your settings of k and n the value returned by MAXLAG is the largest permissible value of m for which the model is not overparameterised. All output quantities in the arrays PARLAG, SE, QQ, X, PVALUE and LOGLHD up to and including lag MAXLAG will be correct.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The computations are believed to be stable.

8 Parallelism and Performance

G13DPF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13DPF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

The time taken is roughly proportional to nmk.
For each order of autoregressive model that has been estimated, G13DPF returns the maximum of the log-likelihood function. An alternative means of choosing the order of a vector AR process is to choose the order for which Akaike's information criterion is smallest. That is, choose the value of l for which -2×LOGLHD l+2 l k 2 is smallest. You should be warned that this does not always lead to the same choice of l as indicated by the sample partial autoregression matrices and the likelihood ratio statistics.

10 Example

This example computes the sample partial autoregression matrices of two time series of length 48 up to lag 10.

10.1 Program Text

Program Text (g13dpfe.f90)

10.2 Program Data

Program Data (g13dpfe.d)

10.3 Program Results

Program Results (g13dpfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13DSF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13DSF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
▸▿ 9 Further Comments
9.1 Timing
9.2 Choice of m
9.3 Checking a White Noise Model
9.4 Approximate Standard Errors
9.5 Alternative Tests
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13DSF is a diagnostic checking routine suitable for use after fitting a vector ARMA model to a multivariate time series using G13DDF. The residual cross-correlation matrices are returned along with an estimate of their asymptotic standard errors and correlations. Also, G13DSF calculates the modified Li–McLeod portmanteau statistic and its significance level for testing model adequacy.

2 Specification

SUBROUTINE G13DSF ( K, N, V, KMAX, IP, IQ, M, PAR, PARHLD, QQ, ISHOW, R0, R, RCM, LDRCM, CHI, IDF, SIGLEV, IW, LIW, WORK, LWORK, IFAIL)
INTEGER | K, N, KMAX, IP, IQ, M, ISHOW, LDRCM, IDF, IW(LIW), LIW, LWORK, IFAIL
REAL (KIND=nag_wp) | V(KMAX,N), PAR((IP+IQ)*K*K), QQ(KMAX,K), R0(KMAX,K), R(KMAX,KMAX,M), RCM(LDRCM,M*K*K), CHI, SIGLEV, WORK(LWORK)
LOGICAL | PARHLD((IP+IQ)*K*K)

3 Description

Let Wt = w 1 t,w 2 t,…,w kt T , for t=1,2,…,n, denote a vector of k time series which is assumed to follow a multivariate ARMA model of the form
Wt-μ= ϕ 1 W t-1-μ+ϕ 2 W t-2-μ+⋯+ϕp W t-p-μ +εt-θ 1ε t-1-θ 2ε t-2-⋯-θqε t-q, (1)
where εt = ε 1 t,ε 2 t,…,ε kt T , for t=1,2,…,n, is a vector of k residual series assumed to be Normally distributed with zero mean and positive definite covariance matrix Σ. The components of εt are assumed to be uncorrelated at non-simultaneous lags. The ϕi and θj are k by k matrices of parameters. ϕi, for i=1,2,…,p, are called the autoregressive (AR) parameter matrices, and θi, for i=1,2,…,q, the moving average (MA) parameter matrices. The parameters in the model are thus the p (k by k) ϕ-matrices, the q (k by k) θ-matrices, the mean vector μ and the residual error covariance matrix Σ. Let
A ϕ= ϕ 1 I 0 . . . 0 ϕ 2 0 I 0 . . 0 . . . . . . ϕ p-1 0 . . . 0 I ϕp 0 . . . 0 0 pk×pk   and  B θ= θ 1 I 0 . . . 0 θ 2 0 I 0 . . 0 . . . . . . θ q-1 0 . . . I θq 0 . . . . 0 qk×qk
where I denotes the k by k identity matrix.
The ARMA model (1) is said to be stationary if the eigenvalues of A ϕ lie inside the unit circle, and invertible if the eigenvalues of B θ lie inside the unit circle. The ARMA model is assumed to be both stationary and invertible. Note that some of the elements of the ϕ- and/or θ-matrices may have been fixed at pre-specified values (for example by calling G13DDF).
The estimated residual cross-correlation matrix at lag l is defined to the k by k matrix R^l whose i,jth element is computed as
r ^ i j l = ∑ t = l + 1 n ε ^ i t - l - ε - i ε ^ j t - ε - j ∑ t = 1 n ε ^ i t - ε - i 2 ∑ t = 1 n ε ^ j t - ε - j 2 ,   l =0,1,…,i​ and ​j=1,2,…,k ,
where ε^it denotes an estimate of the tth residual for the ith series ε it and ε-i=∑t=1 n ε^it/n. (Note that R^l is an estimate of E ε t-l εtT, where E is the expected value.)
A modified portmanteau statistic, Q m *, is calculated from the formula (see Li and McLeod (1981))
Q m * = k 2 m m+1 2 n + n ∑ l=1 m r^ l T R^ 0 -1 ⊗ R^ 0 -1 r^ l ,
where ⊗ denotes Kronecker product, R^0 is the estimated residual cross-correlation matrix at lag zero and r^l=vec R^lT , where vec of a k by k matrix is a vector with the i,jth element in position i-1 k+j. m denotes the number of residual cross-correlation matrices computed. (Advice on the choice of m is given in Section 9.2.) Let lC denote the total number of ‘free’ parameters in the ARMA model excluding the mean, μ, and the residual error covariance matrix Σ. Then, under the hypothesis of model adequacy, Q m *, has an asymptotic χ 2-distribution on m k 2-lC degrees of freedom.
Let r^̲=vec R 1 T ,vec R 2 T ,…,vec RmT then the covariance matrix of r^̲ is given by
Var r̲^=Y-X XT G GT X-1XT/n,
where Y=Im⊗Δ⊗Δ and G=Im G GT. Δ is the dispersion matrix Σ in correlation form and G a nonsingular k by k matrix such that G GT=Δ-1 and GΔ GT=Ik. The construction of the matrix X is discussed in Li and McLeod (1981). (Note that the mean, μ, plays no part in calculating Var r̲^ and therefore is not required as input to G13DSF.)

4 References

Li W K and McLeod A I (1981) Distribution of the residual autocorrelations in multivariate ARMA time series models J. Roy. Statist. Soc. Ser. B 43 231–239

5 Arguments

The output quantities K, N, V, KMAX, IP, IQ, PAR, PARHLD and QQ from G13DDF are suitable for input to G13DSF.
1:   K – INTEGERInput
On entry: k, the number of residual time series.
Constraint: K≥1.
2:   N – INTEGERInput
On entry: n, the number of observations in each residual series.
3:   V KMAXN – REAL (KIND=nag_wp) arrayInput
On entry: V it must contain an estimate of the ith component of εt, for i=1,2,…,k and t=1,2,…,n.
Constraints:
  • no two rows of V may be identical;
  • in each row there must be at least two distinct elements.
4:   KMAX – INTEGERInput
On entry: the first dimension of the arrays V, QQ and R0 and
Constraint: KMAX≥K.
5:   IP – INTEGERInput
On entry: p, the number of AR parameter matrices.
Constraint: IP≥0.
6:   IQ – INTEGERInput
On entry: q, the number of MA parameter matrices.
Constraint: IQ≥0.
Note: IP=IQ=0 is not permitted.
7:   M – INTEGERInput
On entry: the value of m, the number of residual cross-correlation matrices to be computed. See Section 9.2 for advice on the choice of M.
Constraint: IP+IQ<M<N.
8:   PAR IP+IQ×K×K – REAL (KIND=nag_wp) arrayInput
On entry: the parameter estimates read in row by row in the order ϕ 1,ϕ 2,…,ϕp, θ 1,θ 2,…,θq.
Thus,
  • if IP>0, PAR l-1×k×k+i-1×k+j must be set equal to an estimate of the i,jth element of ϕl, for l=1,2,…,p and i=1,2,…,k;
  • if IQ≥0, PAR p×k×k+l-1×k×k+i-1×k+j must be set equal to an estimate of the i,jth element of θl, for l=1,2,…,q and i=1,2,…,k.
The first p×k×k elements of PAR must satisfy the stationarity condition and the next q×k×k elements of PAR must satisfy the invertibility condition.
9:   PARHLD IP+IQ×K×K – LOGICAL arrayInput
On entry: PARHLD i must be set to .TRUE. if PAR i has been held constant at a pre-specified value and .FALSE. if PAR i is a free parameter, for i=1,2,…,p+q×k×k.
10:   QQ KMAXK – REAL (KIND=nag_wp) arrayInput/Output
On entry: QQ ij is an efficient estimate of the i,jth element of Σ. The lower triangle only is needed.
Constraint: QQ must be positive definite.
On exit: if IFAIL≠1, then the upper triangle is set equal to the lower triangle.
11:   ISHOW – INTEGERInput
On entry: must be nonzero if the residual cross-correlation matrices r^ij l and their standard errors se r^ij l, the modified portmanteau statistic with its significance and a summary table are to be printed. The summary table indicates which elements of the residual correlation matrices are significant at the 5% level in either a positive or negative direction; i.e., if r^ij l>1.96×se r^ij l then a ‘+’ is printed, if r^ij l<-1.96×se r^ij l then a ‘-’ is printed, otherwise a fullstop (.) is printed. The summary table is only printed if k≤6 on entry.
The residual cross-correlation matrices, their standard errors and the modified portmanteau statistic with its significance are available also as output variables in R, RCM, CHI, IDF and SIGLEV.
12:   R0 KMAXK – REAL (KIND=nag_wp) arrayOutput
On exit: if i≠j, then R0 ij contains an estimate of the i,jth element of the residual cross-correlation matrix at lag zero, R^0. When i=j, R0 ij contains the standard deviation of the ith residual series. If IFAIL=3 on exit then the first K rows and columns of R0 are set to zero.
13:   R KMAXKMAXM – REAL (KIND=nag_wp) arrayOutput
On exit: R lij is an estimate of the i,jth element of the residual cross-correlation matrix at lag l, for i=1,2,…,k, j=1,2,…,k and l=1,2,…,m. If IFAIL=3 on exit then all elements of R are set to zero.
14:   RCM LDRCM M×K×K – REAL (KIND=nag_wp) arrayOutput
On exit: the estimated standard errors and correlations of the elements in the array R. The correlation between R lij and R l 2i 2j 2 is returned as RCM st where s=l-1×k×k+j-1×k+i and t=l 2-1×k×k+j 2-1×k+i 2 except that if s=t, then RCM st contains the standard error of R lij. If on exit, IFAIL≥5, then all off-diagonal elements of RCM are set to zero and all diagonal elements are set to 1/n.
15:   LDRCM – INTEGERInput
On entry: the first dimension of the array RCM as declared in the (sub)program from which G13DSF is called.
Constraint: LDRCM≥M×K×K.
16:   CHI – REAL (KIND=nag_wp)Output
On exit: the value of the modified portmanteau statistic, Q m *. If IFAIL=3 on exit then CHI is returned as zero.
17:   IDF – INTEGEROutput
On exit: the number of degrees of freedom of CHI.
18:   SIGLEV – REAL (KIND=nag_wp)Output
On exit: the significance level of CHI based on IDF degrees of freedom. If IFAIL=3 on exit, SIGLEV is returned as one.
19:   IW LIW – INTEGER arrayWorkspace
20:   LIW – INTEGERInput
On entry: the dimension of the array IW as declared in the (sub)program from which G13DSF is called.
Constraint: LIW≥K×max IP,IQ.
21:   WORK LWORK – REAL (KIND=nag_wp) arrayWorkspace
22:   LWORK – INTEGERInput
On entry: the dimension of the array WORK as declared in the (sub)program from which G13DSF is called.
Constraint: if LWORK≥k⁢n+KMAX+2+m⁢k 2⁢NPAR+m⁢k 2+1+ 3⁢k 2+NPAR+1⁢NPAR, NPAR=p+q k 2.
23:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if IFAIL≠0 on exit, the recommended value is -1. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Note: G13DSF may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the routine:
IFAIL=1
On entry, | K<1,
or | KMAX<K,
or | IP<0,
or | IQ<0,
or | IP=IQ=0,
or | M≤IP+IQ,
or | M≥N,
or | LDRCM<M×K×K,
or | LIW is too small,
or | LWORK is too small.
IFAIL=2
On entry, either QQ is not positive definite or the autoregressive parameter matrices are extremely close to or outside the stationarity region, or the moving average parameter matrices are extremely close to or outside the invertibility region. To proceed, you must supply different parameter estimates in the arrays PAR and QQ.
IFAIL=3
On entry, at least one of the k residual series is such that all its elements are practically identical giving zero (or near zero) variance or at least two of the residual series are identical. In this case CHI is set to zero, SIGLEV to one and all the elements of R0 and R set to zero.
IFAIL=4
This is an unlikely exit brought about by an excessive number of iterations being needed to evaluate the zeros of the determinantal polynomials det A ϕ and det B θ. All output arguments are undefined.
IFAIL=5
On entry, either the eigenvalues and eigenvectors of Δ (the matrix QQ in correlation form) could not be computed or the determinantal polynomials det A ϕ and det B θ have a factor in common. To proceed, you must either supply different parameter estimates in the array QQ or delete this common factor from the model. In this case, the off-diagonal elements of RCM are returned as zero and the diagonal elements set to 1/n. All other output quantities will be correct.
IFAIL=6
This is an unlikely exit. At least one of the diagonal elements of RCM was found to be either negative or zero. In this case all off-diagonal elements of RCM are returned as zero and all diagonal elements of RCM set to 1/n.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The computations are believed to be stable.

8 Parallelism and Performance

G13DSF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13DSF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

9.1 Timing

The time taken by G13DSF depends upon the number of residual cross-correlation matrices to be computed, m, and the number of time series, k.

9.2 Choice of m

The number of residual cross-correlation matrices to be computed, m, should be chosen to ensure that when the ARMA model (1) is written as either an infinite order autoregressive process, i.e.,
Wt-μ=∑j=1∞πj W t-j-μ+εt
or as an infinite order moving average process, i.e.,
Wt-μ=∑j= 1∞ψjε t-j+εt
then the two sequences of k by k matrices π 1,π 2,… and ψ 1,ψ 2,… are such that πj and ψj are approximately zero for j>m. An overestimate of m is therefore preferable to an under-estimate of m. In many instances the choice m=10 will suffice. In practice, to be on the safe side, you should try setting m=20.

9.3 Checking a ‘White Noise’ Model

If you have fitted the ‘white noise’ model
Wt-μ=εt
then G13DSF should be entered with p=1, q=0, and the first k 2 elements of PAR and PARHLD set to zero and .TRUE. respectively.

9.4 Approximate Standard Errors

When IFAIL=5 or 6 all the standard errors in RCM are set to 1/n. This is the asymptotic standard error of r^ij l when all the autoregressive and moving average parameters are assumed to be known rather than estimated.

9.5 Alternative Tests

R^0 is useful in testing for instantaneous causality. If you wish to carry out a likelihood ratio test then the covariance matrix at lag zero C^0 can be used. It can be recovered from R^0 by setting
C^0 i,j =R^0 i,j×R^0 i,i×R^0 j,j, for ​i≠j =R^0 i,j×R^0 i,j, for ​i=j

10 Example

This example fits a bivariate AR(1) model to two series each of length 48. μ has been estimated but ϕ 1 2,1 has been constrained to be zero. Ten residual cross-correlation matrices are to be computed.

10.1 Program Text

Program Text (g13dsfe.f90)

10.2 Program Data

Program Data (g13dsfe.d)

10.3 Program Results

Program Results (g13dsfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13DXF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13DXF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13DXF calculates the zeros of a vector autoregressive (or moving average) operator. This routine is likely to be used in conjunction with G05PJF, G13ASF, G13DDF or G13DSF.

2 Specification

SUBROUTINE G13DXF ( K, IP, PAR, RR, RI, RMOD, WORK, IWORK, IFAIL)
INTEGER | K, IP, IWORK(K*IP), IFAIL
REAL (KIND=nag_wp) | PAR(IP*K*K), RR(K*IP), RI(K*IP), RMOD(K*IP), WORK(K*K*IP*IP)

3 Description

Consider the vector autoregressive moving average (VARMA) model
Wt-μ=ϕ 1 W t-1-μ+ϕ 2 W t-2-μ+⋯+ϕp W t-p-μ+εt-θ 1ε t-1-θ 2ε t-2-⋯-θqε t-q, (1)
where Wt denotes a vector of k time series and εt is a vector of k residual series having zero mean and a constant variance-covariance matrix. The components of εt are also assumed to be uncorrelated at non-simultaneous lags. ϕ 1,ϕ 2,…,ϕp denotes a sequence of k by k matrices of autoregressive (AR) parameters and θ 1,θ 2,…,θq denotes a sequence of k by k matrices of moving average (MA) parameters. μ is a vector of length k containing the series means. Let
A ϕ= ϕ 1 I 0 . . . 0 ϕ 2 0 I 0 . . 0 . . . . . . ϕ p-1 0 . . . 0 I ϕp 0 . . . 0 0 pk×pk
where I denotes the k by k identity matrix.
The model (1) is said to be stationary if the eigenvalues of A ϕ lie inside the unit circle. Similarly let
B θ= θ 1 I 0 . . . 0 θ 2 0 I 0 . . 0 . . . . . . θ q-1 0 . . . 0 I θq 0 . . . 0 0 qk×qk .
Then the model is said to be invertible if the eigenvalues of B θ lie inside the unit circle.
G13DXF returns the pk eigenvalues of A ϕ (or the qk eigenvalues of B θ) along with their moduli, in descending order of magnitude. Thus to check for stationarity or invertibility you should check whether the modulus of the largest eigenvalue is less than one.

4 References

Wei W W S (1990) Time Series Analysis: Univariate and Multivariate Methods Addison–Wesley

5 Arguments

1:   K – INTEGERInput
On entry: k, the dimension of the multivariate time series.
Constraint: K≥1.
2:   IP – INTEGERInput
On entry: the number of AR (or MA) parameter matrices, p (or q).
Constraint: IP≥1.
3:   PAR IP×K×K – REAL (KIND=nag_wp) arrayInput
On entry: the AR (or MA) parameter matrices read in row by row in the order ϕ 1,ϕ 2,…,ϕp (or θ 1,θ 2,…,θq). That is, PAR l-1×k×k+i-1×k+j must be set equal to the i,jth element of ϕl, for l=1,2,…,p (or the i,jth element of θl, for l=1,2,…,q).
4:   RR K×IP – REAL (KIND=nag_wp) arrayOutput
On exit: the real parts of the eigenvalues.
5:   RI K×IP – REAL (KIND=nag_wp) arrayOutput
On exit: the imaginary parts of the eigenvalues.
6:   RMOD K×IP – REAL (KIND=nag_wp) arrayOutput
On exit: the moduli of the eigenvalues.
7:   WORK K×K×IP×IP – REAL (KIND=nag_wp) arrayWorkspace
8:   IWORK K×IP – INTEGER arrayWorkspace
9:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | K<1,
or | IP<1.
IFAIL=2
An excessive number of iterations are needed to evaluate the eigenvalues of A ϕ (or B θ). This is an unlikely exit. All output arguments are undefined.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The accuracy of the results depends on the original matrix and the multiplicity of the roots.

8 Parallelism and Performance

G13DXF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13DXF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

The time taken is approximately proportional to k p 3 (or k q 3).

10 Example

This example finds the eigenvalues of A ϕ where k=2 and p=1 and ϕ 1= 0.802 0.065 0.000 0.575 .

10.1 Program Text

Program Text (g13dxfe.f90)

10.2 Program Data

Program Data (g13dxfe.d)

10.3 Program Results

Program Results (g13dxfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13EAF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13EAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13EAF performs a combined measurement and time update of one iteration of the time-varying Kalman filter using a square root covariance filter.

2 Specification

SUBROUTINE G13EAF ( N, M, L, A, LDS, B, STQ, Q, LDQ, C, LDM, R, S, K, H, TOL, IWK, WK, IFAIL)
INTEGER | N, M, L, LDS, LDQ, LDM, IWK(M), IFAIL
REAL (KIND=nag_wp) | A(LDS,N), B(LDS,L), Q(LDQ,*), C(LDM,N), R(LDM,M), S(LDS,N), K(LDS,M), H(LDM,M), TOL, WK((N+M)*(N+M+L))
LOGICAL | STQ

3 Description

The Kalman filter arises from the state space model given by:
X i+1=AiXi+BiWi, Var Wi=Qi Yi=CiXi+Vi, Var Vi=Ri
where Xi is the state vector of length n at time i, Yi is the observation vector of length m at time i, and Wi of length l and Vi of length m are the independent state noise and measurement noise respectively.
The estimate of Xi given observations Y 1 to Y i-1 is denoted by X^i∣i-1 with state covariance matrix Var X^i∣i-1=P i∣i-1=Si SiT, while the estimate of Xi given observations Y 1 to Yi is denoted by X^i∣i with covariance matrix Var X^i∣i=P i∣i. The update of the estimate, X^i∣i-1, from time i to time i+1, is computed in two stages. First, the measurement-update is given by
X^i∣i=X^i∣i-1+Ki Yi-CiX^i∣i-1 (1)
and
P i∣i=I-KiCi P i∣i-1 (2)
where Ki=P i∣i-1 CiT CiP i∣i-1 CiT +Ri -1 is the Kalman gain matrix. The second stage is the time-update for X which is given by
X^i+1∣i=AiX^i∣i+DiUi (3)
and
P i+1∣i=AiP i∣i AiT +BiQi BiT (4)
where DiUi represents any deterministic control used.
The square root covariance filter algorithm provides a stable method for computing the Kalman gain matrix and the state covariance matrix. The algorithm can be summarised as
Ri 1/2 CiSi 0 0 AiSi Bi Qi 1/2 U= Hi 1/2 0 0 Gi S i+1 0 (5)
where U is an orthogonal transformation triangularizing the left-hand pre-array to produce the right-hand post-array. The relationship between the Kalman gain matrix, Ki, and Gi is given by
AiKi=Gi Hi 1/2 -1.
G13EAF requires the input of the lower triangular Cholesky factors of the noise covariance matrices Ri 1/2 and, optionally, Qi 1/2 and the lower triangular Cholesky factor of the current state covariance matrix, Si, and returns the product of the matrices Ai and Ki, AiKi, the Cholesky factor of the updated state covariance matrix S i+1 and the matrix Hi 1/2 used in the computation of the likelihood for the model.

4 References

Vanbegin M, van Dooren P and Verhaegen M H G (1989) Algorithm 675: FORTRAN subroutines for computing the square root covariance filter and square root information filter in dense or Hessenberg forms ACM Trans. Math. Software 15 243–256
Verhaegen M H G and van Dooren P (1986) Numerical aspects of different Kalman filter implementations IEEE Trans. Auto. Contr. AC-31 907–917

5 Arguments

1:   N – INTEGERInput
On entry: n, the size of the state vector.
Constraint: N≥1.
2:   M – INTEGERInput
On entry: m, the size of the observation vector.
Constraint: M≥1.
3:   L – INTEGERInput
On entry: l, the dimension of the state noise.
Constraint: L≥1.
4:   A LDSN – REAL (KIND=nag_wp) arrayInput
On entry: the state transition matrix, Ai.
5:   LDS – INTEGERInput
On entry: the first dimension of the arrays A, B, S and K as declared in the (sub)program from which G13EAF is called.
Constraint: LDS≥N.
6:   B LDSL – REAL (KIND=nag_wp) arrayInput
On entry: the noise coefficient matrix Bi.
7:   STQ – LOGICALInput
On entry: if STQ=.TRUE., the state noise covariance matrix Qi is assumed to be the identity matrix. Otherwise the lower triangular Cholesky factor, Qi 1/2, must be provided in Q.
8:   Q LDQ* – REAL (KIND=nag_wp) arrayInput
Note: the second dimension of the array Q must be at least L if STQ=.FALSE. and at least 1 if STQ=.TRUE..
On entry: if STQ=.FALSE., Q must contain the lower triangular Cholesky factor of the state noise covariance matrix, Qi 1/2. Otherwise Q is not referenced.
9:   LDQ – INTEGERInput
On entry: the first dimension of the array Q as declared in the (sub)program from which G13EAF is called.
Constraints:
  • if STQ=.FALSE., LDQ≥L;
  • otherwise LDQ≥1.
10:   C LDMN – REAL (KIND=nag_wp) arrayInput
On entry: the measurement coefficient matrix, Ci.
11:   LDM – INTEGERInput
On entry: the first dimension of the arrays C, R and H as declared in the (sub)program from which G13EAF is called.
Constraint: LDM≥M.
12:   R LDMM – REAL (KIND=nag_wp) arrayInput
On entry: the lower triangular Cholesky factor of the measurement noise covariance matrix Ri 1/2.
13:   S LDSN – REAL (KIND=nag_wp) arrayInput/Output
On entry: the lower triangular Cholesky factor of the state covariance matrix, Si.
On exit: the lower triangular Cholesky factor of the state covariance matrix, S i+1.
14:   K LDSM – REAL (KIND=nag_wp) arrayOutput
On exit: the Kalman gain matrix, Ki, premultiplied by the state transition matrix, Ai, AiKi.
15:   H LDMM – REAL (KIND=nag_wp) arrayOutput
On exit: the lower triangular matrix Hi 1/2.
16:   TOL – REAL (KIND=nag_wp)Input
On entry: the tolerance used to test for the singularity of Hi 1/2. If 0.0≤TOL<m 2×machine precision, then m 2×machine precision is used instead. The inverse of the condition number of H 1/2 is estimated by a call to F07TGF (DTRCON). If this estimate is less than TOL then H 1/2 is assumed to be singular.
Suggested value: TOL=0.0.
Constraint: TOL≥0.0.
17:   IWK M – INTEGER arrayWorkspace
18:   WK N+M×N+M+L – REAL (KIND=nag_wp) arrayWorkspace
19:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | N<1,
or | M<1,
or | L<1,
or | LDS<N,
or | LDM<M,
or | STQ=.TRUE. and LDQ<1,
or | STQ=.FALSE. and LDQ<L,
or | TOL<0.0.
IFAIL=2
The matrix Hi 1/2 is singular.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The use of the square root algorithm improves the stability of the computations as compared with the direct coding of the Kalman filter. The accuracy will depend on the model.

8 Parallelism and Performance

G13EAF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13EAF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

For models with time-invariant A,B and C, G13EBF can be used.
The estimate of the state vector X^i+1∣i can be computed from X^i∣i-1 by
X^i+1∣i=AiX^i∣i-1+A Kiri
where
ri=Yi-CiX^i∣i- 1
are the independent one step prediction residuals. The required matrix-vector multiplications can be performed by F06PAF (DGEMV).
If Wi and Vi are independent multivariate Normal variates then the log-likelihood for observations i=1,2,…,t is given by
l θ = κ - 12 ∑ i=1 t l n det Hi - 12 ∑ i=1 t Yi - Ci X i∣i-1 T H i -1 Yi - Ci X i∣i-1
where κ is a constant.
The Cholesky factors of the covariance matrices can be computed using F07FDF (DPOTRF).
Note that the model
X i+1=AiXi+Wi, Var Wi=Qi Yi=CiXi+Vi, Var Vi=Ri
can be specified either with B set to the identity matrix and STQ=.FALSE. and the matrix Q 1/2 input in Q or with STQ=.TRUE. and B set to Q 1/2.
The algorithm requires 76 n 3+n 2 52 m+l+n 12 l 2+m 2 operations and is backward stable (see Verhaegen and van Dooren (1986)).

10 Example

This example first inputs the number of updates to be computed and the problem sizes. The initial state vector and state covariance matrix are input followed by the model matrices Ai,Bi,Ci,Ri and optionally Qi. The Cholesky factors of the covariance matrices can be computed if required. The model matrices can be input at each update or only once at the first step. At each update the observed values are input and the residuals are computed and printed and the estimate of the state vector, X^i∣i-1, and the deviance are updated. The deviance is -2×log-likelihood ignoring the constant. After the final update the state covariance matrix is computed from S and printed along with final estimate of the state vector and the value of the deviance.
The data is for a two-dimensional time series to which a VARMA1,1 has been fitted. For the specification of a VARMA model as a state space model see the G13 Chapter Introduction. The initial value of P, P 0, is the solution to
P 0=A 1P 0 A 1 T +B 1Q 1 B 1 T .
For convenience, the mean of each series is input before the first update and subtracted from the observations before the measurement update is computed.

10.1 Program Text

Program Text (g13eafe.f90)

10.2 Program Data

Program Data (g13eafe.d)

10.3 Program Results

Program Results (g13eafe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13EBF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13EBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13EBF performs a combined measurement and time update of one iteration of the time-invariant Kalman filter using a square root covariance filter.

2 Specification

SUBROUTINE G13EBF ( TRANSF, N, M, L, A, LDS, B, STQ, Q, LDQ, C, LDM, R, S, K, H, U, TOL, IWK, WK, IFAIL)
INTEGER | N, M, L, LDS, LDQ, LDM, IWK(M), IFAIL
REAL (KIND=nag_wp) | A(LDS,N), B(LDS,L), Q(LDQ,*), C(LDM,N), R(LDM,M), S(LDS,N), K(LDS,M), H(LDM,M), U(LDS,*), TOL, WK((N+M)*(N+M+L))
LOGICAL | STQ
CHARACTER(1) | TRANSF

3 Description

The Kalman filter arises from the state space model given by
X i+1=A Xi+B Wi, Var Wi=Qi Yi=C Xi+Vi, Var Vi=Ri
where Xi is the state vector of length n at time i, Yi is the observation vector of length m at time i and Wi of length l and Vi of length m are the independent state noise and measurement noise respectively. The matrices A,B and C are time invariant.
The estimate of Xi given observations Y 1 to Y i-1 is denoted by X^i∣i-1 with state covariance matrix Var X^i∣i-1=P i∣i-1=Si SiT while the estimate of Xi given observations Y 1 to Yi is denoted by X^i∣i with covariance matrix Var X^i∣i=P i∣i. The update of the estimate, X^i∣i-1, from time i to time i+1 is computed in two stages. First, the measurement-update is given by
X^i∣i=X^i∣i-1+Ki Yi-C X^i∣i-1 (1)
where Ki=P i∣i CTC P i∣i CT+Ri -1 is the Kalman gain matrix. The second stage is the time-update for X, which is given by
X^i+1∣i=A X^i∣i+DiUi (2)
where DiUi represents any deterministic control used.
The square root covariance filter algorithm provides a stable method for computing the Kalman gain matrix and the state covariance matrix. The algorithm can be summarised as
Ri 1/2 0 C Si 0 B Qi 1/2 A Si U= Hi 1/2 0 0 Gi S i+1 0
where U is an orthogonal transformation triangularizing the left-hand pre-array to produce the right-hand post-array. The triangularization is carried out via Householder transformations exploiting the zero pattern of the pre-array. The relationship between the Kalman gain matrix Ki and Gi is given by
A Ki=Gi Hi 1/2 -1.
In order to exploit the invariant parts of the model to simplify the computation of U the results for the transformed state space U*X are computed where U* is the transformation that reduces the matrix pair A,C to lower observer Hessenberg form. That is, the matrix U* is computed such that the compound matrix
C U*T U*A U*T
is a lower trapezoidal matrix. Further the matrix B is transformed to U*B. These transformations need only be computed once at the start of a series, and G13EBF will, optionally, compute them. G13EBF returns transformed matrices U*A U*T, U*B, C U*T and U*A Ki, the Cholesky factor of the updated transformed state covariance matrix S i+1* (where U*P i+1∣i U*T=S i+1*S i+1 *T) and the matrix Hi 1/2, valid for both transformed and original models, which is used in the computation of the likelihood for the model. Note that the covariance matrices Qi and Ri can be time-varying.

4 References

Vanbegin M, van Dooren P and Verhaegen M H G (1989) Algorithm 675: FORTRAN subroutines for computing the square root covariance filter and square root information filter in dense or Hessenberg forms ACM Trans. Math. Software 15 243–256
Verhaegen M H G and van Dooren P (1986) Numerical aspects of different Kalman filter implementations IEEE Trans. Auto. Contr. AC-31 907–917

5 Arguments

1:   TRANSF – CHARACTER(1)Input
On entry: indicates whether to transform the input matrix pair A,C to lower observer Hessenberg form. The transformation will only be required on the first call to G13EBF.
TRANSF='T'
The matrices in arrays A and C are transformed to lower observer Hessenberg form and the matrices in B and S are transformed as described in Section 3.
TRANSF='H'
The matrices in arrays A, C and B should be as returned from a previous call to G13EBF with TRANSF='T'.
Constraint: TRANSF='T' or 'H'.
2:   N – INTEGERInput
On entry: n, the size of the state vector.
Constraint: N≥1.
3:   M – INTEGERInput
On entry: m, the size of the observation vector.
Constraint: M≥1.
4:   L – INTEGERInput
On entry: l, the dimension of the state noise.
Constraint: L≥1.
5:   A LDSN – REAL (KIND=nag_wp) arrayInput/Output
On entry: if TRANSF='T', the state transition matrix, A.
If TRANSF='H', the transformed matrix as returned by a previous call to G13EBF with TRANSF='T'.
On exit: if TRANSF='T', the transformed matrix, U*A U*T, otherwise A is unchanged.
6:   LDS – INTEGERInput
On entry: the first dimension of the arrays A, B, S, K and U as declared in the (sub)program from which G13EBF is called.
Constraint: LDS≥N.
7:   B LDSL – REAL (KIND=nag_wp) arrayInput/Output
On entry: if TRANSF='T', the noise coefficient matrix B.
If TRANSF='H', the transformed matrix as returned by a previous call to G13EBF with TRANSF='T'.
On exit: if TRANSF='T', the transformed matrix, U*B, otherwise B is unchanged.
8:   STQ – LOGICALInput
On entry: if STQ=.TRUE., the state noise covariance matrix Qi is assumed to be the identity matrix. Otherwise the lower triangular Cholesky factor, Qi 1/2, must be provided in Q.
9:   Q LDQ* – REAL (KIND=nag_wp) arrayInput
Note: the second dimension of the array Q must be at least L if STQ=.FALSE. and at least 1 if STQ=.TRUE..
On entry: if STQ=.FALSE., Q must contain the lower triangular Cholesky factor of the state noise covariance matrix, Qi 1/2. Otherwise Q is not referenced.
10:   LDQ – INTEGERInput
On entry: the first dimension of the array Q as declared in the (sub)program from which G13EBF is called.
Constraints:
  • if STQ=.FALSE., LDQ≥L;
  • otherwise LDQ≥1.
11:   C LDMN – REAL (KIND=nag_wp) arrayInput/Output
On entry: if TRANSF='T', the measurement coefficient matrix, C.
If TRANSF='H', the transformed matrix as returned by a previous call to G13EBF with TRANSF='T'.
On exit: if TRANSF='T', the transformed matrix, C U*T, otherwise C is unchanged.
12:   LDM – INTEGERInput
On entry: the first dimension of the arrays C, R and H as declared in the (sub)program from which G13EBF is called.
Constraint: LDM≥M.
13:   R LDMM – REAL (KIND=nag_wp) arrayInput
On entry: the lower triangular Cholesky factor of the measurement noise covariance matrix Ri 1/2.
14:   S LDSN – REAL (KIND=nag_wp) arrayInput/Output
On entry: if TRANSF='T' the lower triangular Cholesky factor of the state covariance matrix, Si.
If TRANSF='H' the lower triangular Cholesky factor of the covariance matrix of the transformed state vector Si* as returned from a previous call to G13EBF with TRANSF='T'.
On exit: the lower triangular Cholesky factor of the transformed state covariance matrix, S i+1*.
15:   K LDSM – REAL (KIND=nag_wp) arrayOutput
On exit: the Kalman gain matrix for the transformed state vector premultiplied by the state transformed transition matrix, U*A Ki.
16:   H LDMM – REAL (KIND=nag_wp) arrayOutput
On exit: the lower triangular matrix Hi 1/2.
17:   U LDS* – REAL (KIND=nag_wp) arrayOutput
Note: the second dimension of the array U must be at least N if TRANSF='T', and at least 1 otherwise.
On exit: if TRANSF='T' the n by n transformation matrix U*, otherwise U is not referenced.
18:   TOL – REAL (KIND=nag_wp)Input
On entry: the tolerance used to test for the singularity of Hi 1/2. If 0.0≤TOL<m 2×machine precision, then m 2×machine precision is used instead. The inverse of the condition number of H 1/2 is estimated by a call to F07TGF (DTRCON). If this estimate is less than TOL then H 1/2 is assumed to be singular.
Suggested value: TOL=0.0.
Constraint: TOL≥0.0.
19:   IWK M – INTEGER arrayWorkspace
20:   WK N+M×N+M+L – REAL (KIND=nag_wp) arrayWorkspace
21:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | TRANSF≠'T' or 'H',
or | N<1,
or | M<1,
or | L<1,
or | LDS<N,
or | LDM<M,
or | STQ=.TRUE. and LDQ<1,
or | STQ=.FALSE. and LDQ<L,
or | TOL<0.0.
IFAIL=2
The matrix Hi 1/2 is singular.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The use of the square root algorithm improves the stability of the computations as compared with the direct coding of the Kalman filter. The accuracy will depend on the model.

8 Parallelism and Performance

G13EBF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13EBF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

For models with time-varying A,B and C, G13EAF can be used.
The initial estimate of the transformed state vector can be computed from the estimate of the original state vector X^1∣0, say, by premultiplying it by U* as returned by G13EBF with TRANSF='T'; that is, X^1∣0*=U*X^1∣0. The estimate of the transformed state vector X^i+1∣i* can be computed from the previous value X^i∣i-1* by
X^i+1∣i*=U*A U*T X^i∣i-1*+U*A Ki ri
where
ri=Yi-C U*T X^i∣i- 1*
are the independent one-step prediction residuals for both the transformed and original model. The estimate of the original state vector can be computed from the transformed state vector as U*T X^1+1∣i*. The required matrix-vector multiplications can be performed by F06PAF (DGEMV).
If Wi and Vi are independent multivariate Normal variates then the log-likelihood for observations i=1,2,…,t is given by
l θ = κ - 12 ∑ i=1 t l n det Hi - 12 ∑ i=1 t Yi - Ci X i∣i-1 T Hi-1 Yi - Ci X i∣i-1
where κ is a constant.
The Cholesky factors of the covariance matrices can be computed using F07FDF (DPOTRF).
Note that the model
X i+1=A Xi+Wi, Var Wi=Qi Yi=C Xi+Vi, Var Vi=Ri
can be specified either with B set to the identity matrix and STQ=.FALSE. and the matrix Q 1/2 input in Q or with STQ=.TRUE. and B set to Q 1/2.
The algorithm requires 16 n 3+n 2 32 m+l+2 n m 2+23 p 3 operations and is backward stable (see Verhaegen and van Dooren (1986)). The transformation to lower observer Hessenberg form requires O n+m n 2 operations.

10 Example

This example first inputs the number of updates to be computed and the problem sizes. The initial state vector and the Cholesky factor of the state covariance matrix are input followed by the model matrices A,B,C,R 1/2 and optionally Q 1/2 (the Cholesky factors of the covariance matrices being input). At the first update the matrices are transformed using the TRANSF='T' option and the initial value of the state vector is transformed. At each update the observed values are input and the residuals are computed and printed and the estimate of the transformed state vector, U^*X i∣i-1, and the deviance are updated. The deviance is -2×log-likelihood ignoring the constant. After the final update the estimate of the state vector is computed from the transformed state vector and the state covariance matrix is computed from S and these are printed along with the value of the deviance.
The data is for a two-dimensional time series to which a VARMA1,1 has been fitted. For the specification of a VARMA model as a state space model see the G13 Chapter Introduction. The means of the two series are included as additional states that do not change over time. The initial value of P, P 0, is the solution to
P 0=A P 0 AT+BQ BT.

10.1 Program Text

Program Text (g13ebfe.f90)

10.2 Program Data

Program Data (g13ebfe.d)

10.3 Program Results

Program Results (g13ebfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13EJF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13EJF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
▸▿ 3 Description
3.1 Unscented Kalman Filter Algorithm
3.2 Sigma Points
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13EJF applies the Unscented Kalman Filter to a nonlinear state space model, with additive noise.
G13EJF uses reverse communication for evaluating the nonlinear functionals of the state space model.

2 Specification

SUBROUTINE G13EJF ( IREVCM, MX, MY, Y, LX, LDLX, LY, LDLY, X, ST, LDST, N, XT, LDXT, FXT, LDFXT, ROPT, LROPT, ICOMM, LICOMM, RCOMM, LRCOMM, IFAIL)
INTEGER | IREVCM, MX, MY, LDLX, LDLY, LDST, N, LDXT, LDFXT, LROPT, ICOMM(LICOMM), LICOMM, LRCOMM, IFAIL
REAL (KIND=nag_wp) | Y(MY), LX(LDLX,*), LY(LDLY,*), X(MX), ST(LDST,*), XT(LDXT,*), FXT(LDFXT,*), ROPT(LROPT), RCOMM(LRCOMM)

3 Description

G13EJF applies the Unscented Kalman Filter (UKF), as described in Julier and Uhlmann (1997b) to a nonlinear state space model, with additive noise, which, at time t, can be described by:
x t+1 =F xt+vt yt =H xt+ut
where xt represents the unobserved state vector of length mx and yt the observed measurement vector of length my. The process noise is denoted vt, which is assumed to have mean zero and covariance structure Σx, and the measurement noise by ut, which is assumed to have mean zero and covariance structure Σy.

3.1 Unscented Kalman Filter Algorithm

Given x^0, an initial estimate of the state and P 0 and initial estimate of the state covariance matrix, the UKF can be described as follows:
(a) Generate a set of sigma points (see section Section 3.2):
Xt = x ^ t-1 x ^ t-1 + γ ⁢ P t-1 x ^ t-1 - γ ⁢ P t-1 (1)
(b) Evaluate the known model function F:
Ft =F Xt (2)
The function F is assumed to accept the mx×n matrix, Xt and return an mx×n matrix, Ft. The columns of both Xt and Ft correspond to different possible states. The notation F t,i is used to denote the ith column of Ft, hence the result of applying F to the ith possible state.
(c) Time Update:
x^t_ | = ∑ i=1 n Wim ⁢ F t,i | (3)
Pt_ | = ∑ i=1 n Wic ⁢ F t,i - x ^ t _ ⁢ F t,i - x ^ t _ T + Σx | (4)
(d) Redraw another set of sigma points (see section Section 3.2):
Yt = x ^ t _ x ^ t _ + γ ⁢ Pt_ x ^ t _ - γ ⁢ Pt_ (5)
(e) Evaluate the known model function H:
Ht =H Yt (6)
The function H is assumed to accept the mx×n matrix, Yt and return an my×n matrix, Ht. The columns of both Yt and Ht correspond to different possible states. As above H t,i is used to denote the ith column of Ht.
(f) Measurement Update:
y ^ t | = ∑ i=1 n Wim ⁢ H t,i | (7)
P y yt | = ∑ i=1 n Wic ⁢ H t,i - y ^ t ⁢ H t,i - y ^ t T + Σy | (8)
P x yt | = ∑ i=1 n Wic ⁢ F t,i - x ^ t _ ⁢ H t,i - y ^ t T | (9)
Kt | = P x yt P y yt-1 | (10)
x^t | = x ^ t _ + Kt ⁢ yt - y ^ t | (11)
Pt | = Pt_ - Kt ⁢ P y yt KtT | (12)
Here Kt is the Kalman gain matrix, x^t is the estimated state vector at time t and Pt the corresponding covariance matrix. Rather than implementing the standard UKF as stated above G13EJF uses the square-root form described in the Haykin (2001).

3.2 Sigma Points

A nonlinear state space model involves propagating a vector of random variables through a nonlinear system and we are interested in what happens to the mean and covariance matrix of those variables. Rather than trying to directly propagate the mean and covariance matrix, the UKF uses a set of carefully chosen sample points, referred to as sigma points, and propagates these through the system of interest. An estimate of the propagated mean and covariance matrix is then obtained via the weighted sample mean and covariance matrix.
For a vector of m random variables, x, with mean μ and covariance matrix Σ, the sigma points are usually constructed as:
Xt = μ μ + γ ⁢ Σ μ - γ ⁢ Σ
When calculating the weighted sample mean and covariance matrix two sets of weights are required, one used when calculating the weighted sample mean, denoted Wm and one used when calculated the weighted sample covariance matrix, denoted Wc. The weights and multiplier, γ, are constructed as follows:
λ =α 2⁢L+κ-L γ =L+λ W i m = λ L+λ i=1 1 2⁢L+λ i=2,3,…,2⁢L+1 W i c = λ L+λ +1-α 2+β i=1 1 2⁢L+λ i=2,3,…,2⁢L+1
where, usually L=m and α,β and κ are constants. The total number of sigma points, n, is given by 2⁢L+1. The constant α is usually set to somewhere in the range 10-4≤α≤1 and for a Gaussian distribution, the optimal values of κ and β are 3-L and 2 respectively.
Rather than redrawing another set of sigma points in (d) of the UKF an alternative method can be used where the sigma points used in (a) are augmented to take into account the process noise. This involves replacing equation (5) with:
Yt = Xt X t,1 + γ ⁢ Σx X t,1 - γ ⁢ Σx (13)
Augmenting the sigma points in this manner requires setting L to 2⁢L (and hence n to 2⁢n-1) and recalculating the weights. These new values are then used for the rest of the algorithm. The advantage of augmenting the sigma points is that it keeps any odd-moments information captured by the original propagated sigma points, at the cost of using a larger number of points.

4 References

Haykin S (2001) Kalman Filtering and Neural Networks John Wiley and Sons
Julier S J (2002) The scaled unscented transformation Proceedings of the 2002 American Control Conference (Volume 6) 4555–4559
Julier S J and Uhlmann J K (1997a) A consistent, debiased method for converting between polar and Cartesian coordinate systems Proceedings of AeroSense97, International Society for Optics and Phonotonics 110–121
Julier S J and Uhlmann J K (1997b) A new extension of the Kalman Filter to nonlinear systems International Symposium for Aerospace/Defense, Sensing, Simulation and Controls (Volume 3) 26

5 Arguments

Note: this routine uses reverse communication. Its use involves an initial entry, intermediate exits and re-entries, and a final exit, as indicated by the argument IREVCM. Between intermediate exits and re-entries, all arguments other than FXT must remain unchanged.
1:   IREVCM – INTEGERInput/Output
On initial entry: must be set to 0 or 3.
If IREVCM=0, it is assumed that t=0, otherwise it is assumed that t≠0 and that G13EJF has been called at least once before at an earlier time step.
On intermediate exit: IREVCM=1 or 2. The value of IREVCM specifies what intermediate values are returned by this routine and what values the calling program must assign to arguments of G13EJF before re-entering the routine. Details of the output and required input are given in the individual argument descriptions.
On intermediate re-entry: IREVCM must remain unchanged.
On final exit: IREVCM=3
Constraint: IREVCM=0, 1, 2 or 3.
2:   MX – INTEGERInput
On entry: mx, the number of state variables.
Constraint: MX≥1.
3:   MY – INTEGERInput
On entry: my, the number of observed variables.
Constraint: MY≥1.
4:   Y MY – REAL (KIND=nag_wp) arrayInput
On entry: yt, the observed data at the current time point.
5:   LX LDLX* – REAL (KIND=nag_wp) arrayInput
Note: the second dimension of the array LX must be at least MX.
On entry: Lx, such that Lx LxT=Σx, i.e., the lower triangular part of a Cholesky decomposition of the process noise covariance structure. Only the lower triangular part of LX is referenced.
If LDLX=0, there is no process noise (vt=0 for all t) and LX is not referenced.
If Σx is time dependent, then the value supplied should be for time t.
6:   LDLX – INTEGERInput
On entry: the first dimension of the array LX as declared in the (sub)program from which G13EJF is called.
Constraint: LDLX=0 or LDLX≥MX.
7:   LY LDLY* – REAL (KIND=nag_wp) arrayInput
Note: the second dimension of the array LY must be at least MY.
On entry: Ly, such that Ly LyT=Σy, i.e., the lower triangular part of a Cholesky decomposition of the observation noise covariance structure. Only the lower triangular part of LY is referenced.
If Σy is time dependent, then the value supplied should be for time t.
8:   LDLY – INTEGERInput
On entry: the first dimension of the array LY as declared in the (sub)program from which G13EJF is called.
Constraint: LDLY≥MY.
9:   X MX – REAL (KIND=nag_wp) arrayInput/Output
On initial entry: x^t-1 the state vector for the previous time point.
On intermediate exit: when
IREVCM=1
X is unchanged.
IREVCM=2
x^t_.
On intermediate re-entry: X must remain unchanged.
On final exit: x^t the updated state vector.
10:   ST LDST* – REAL (KIND=nag_wp) arrayInput/Output
Note: the second dimension of the array ST must be at least MX.
On initial entry: St, such that S t-1 S t-1 T=P t-1, i.e., the lower triangular part of a Cholesky decomposition of the state covariance matrix at the previous time point. Only the lower triangular part of ST is referenced.
On intermediate exit: when
IREVCM=1
ST is unchanged.
IREVCM=2
St_, the lower triangular part of a Cholesky factorization of Pt_.
On intermediate re-entry: ST must remain unchanged.
On final exit: St, the lower triangular part of a Cholesky factorization of the updated state covariance matrix.
11:   LDST – INTEGERInput
On entry: the first dimension of the array ST as declared in the (sub)program from which G13EJF is called.
Constraint: LDST≥MX.
12:   N – INTEGERInput/Output
On initial entry: the value used in the sizing of the FXT and XT arrays. The value of N supplied must be at least as big as the maximum number of sigma points that the algorithm will use. G13EJF allows sigma points to be calculated in two ways during the measurement update; they can be redrawn or augmented. Which is used is controlled by ROPT.
If redrawn sigma points are used, then the maximum number of sigma points will be 2⁢mx+1, otherwise the maximum number of sigma points will be 4⁢mx+1.
On intermediate exit: the number of sigma points actually being used.
On intermediate re-entry: N must remain unchanged.
On final exit: reset to its value on initial entry.
Constraints:
if IREVCM=0 or 3,
  • if redrawn sigma points are used, N≥2×MX+1;
  • otherwise N≥4×MX+1.
13:   XT LDXT* – REAL (KIND=nag_wp) arrayInput/Output
Note: the second dimension of the array XT must be at least max MY,N.
On initial entry: need not be set.
On intermediate exit: Xt when IREVCM=1, otherwise Yt.
For the jth sigma point, the value for the ith parameter is held in XT ij, for i=1,2,…,MX and j=1,2,…,N.
On intermediate re-entry: XT must remain unchanged.
On final exit: the contents of XT are undefined.
14:   LDXT – INTEGERInput
On entry: the first dimension of the array XT as declared in the (sub)program from which G13EJF is called.
Constraint: LDXT≥MX.
15:   FXT LDFXT* – REAL (KIND=nag_wp) arrayInput/Output
Note: the second dimension of the array FXT must be at least N+max MX,MY.
On initial entry: need not be set.
On intermediate exit: the contents of FXT are undefined.
On intermediate re-entry: F Xt when IREVCM=1, otherwise H Yt for the values of Xt and Yt held in XT.
For the jth sigma point the value for the ith parameter should be held in FXT ij, for j=1,2,…,N. When IREVCM=1, i=1,2,…,MX and when IREVCM=2, i=1,2,…,MY.
On final exit: the contents of FXT are undefined.
16:   LDFXT – INTEGERInput
On entry: the first dimension of the array FXT as declared in the (sub)program from which G13EJF is called.
Constraint: LDFXT≥max MX,MY.
17:   ROPT LROPT – REAL (KIND=nag_wp) arrayInput
On entry: optional arguments. The default value will be used for ROPT i if LROPT<i. Setting LROPT=0 will use the default values for all optional arguments and ROPT need not be set.
ROPT 1
If set to 1 then the second set of sigma points are redrawn, as given by equation (5). If set to 2 then the second set of sigma points are generated via augmentation, as given by equation (13).
Default is for the sigma points to be redrawn (i.e., ROPT 1=1)
ROPT 2
κx, value of κ used when constructing the first set of sigma points, Xt.
Defaults to 3-MX.
ROPT 3
αx, value of α used when constructing the first set of sigma points, Xt.
Defaults to 1.
ROPT 4
βx, value of β used when constructing the first set of sigma points, Xt.
Defaults to 2.
ROPT 5
Value of κ used when constructing the second set of sigma points, Yt.
Defaults to 3-2×MX when LDLX≠0 and the second set of sigma points are augmented and κx otherwise.
ROPT 6
Value of α used when constructing the second set of sigma points, Yt.
Defaults to αx.
ROPT 7
Value of β used when constructing the second set of sigma points, Yt.
Defaults to βx.
Constraints:
  • ROPT 1=1 or 2;
  • ROPT 2>-MX;
  • ROPT 5>-2×MX when LDLY≠0 and the second set of sigma points are augmented, otherwise ROPT 5>-MX;
  • ROPT i>0, for i=3,6.
18:   LROPT – INTEGERInput
On entry: length of the options array ROPT.
Constraint: 0≤LROPT≤7.
19:   ICOMM LICOMM – INTEGER arrayCommunication Array
On initial entry: ICOMM need not be set.
On intermediate exit: ICOMM is used for storage between calls to G13EJF.
On intermediate re-entry: ICOMM must remain unchanged.
On final exit: ICOMM is not defined.
20:   LICOMM – INTEGERInput
On entry: the length of the array ICOMM. If LICOMM is too small and LICOMM≥2 then IFAIL=201 is returned and the minimum value for LICOMM and LRCOMM are given by ICOMM 1 and ICOMM 2 respectively.
Constraint: LICOMM≥30.
21:   RCOMM LRCOMM – REAL (KIND=nag_wp) arrayCommunication Array
On initial entry: RCOMM need not be set.
On intermediate exit: RCOMM is used for storage between calls to G13EJF.
On intermediate re-entry: RCOMM must remain unchanged.
On final exit: RCOMM is not defined.
22:   LRCOMM – INTEGERInput
On entry: the length of the array RCOMM. If LRCOMM is too small and LICOMM≥2 then IFAIL=202 is returned and the minimum value for LICOMM and LRCOMM are given by ICOMM 1 and ICOMM 2 respectively.
Suggested value: LRCOMM = 30 + MY + MX × MY + 1+nb × max MX,MY , where nb is the optimal block size. In most cases a block size of 128 will be sufficient.
Constraint: LRCOMM≥30+MY+MX×MY+2×max MX,MY.
23:   IFAIL – INTEGERInput/Output
On initial entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if IFAIL≠0 on exit, the recommended value is -1. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On final exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=11
On entry, IREVCM=value.
Constraint: IREVCM=0, 1, 2 or 3.
IFAIL=21
On entry, MX=value.
Constraint: MX≥1.
IFAIL=22
MX has changed between calls.
On intermediate entry, MX=value.
On initial entry, MX=value.
IFAIL=31
On entry, MY=value.
Constraint: MY≥1.
IFAIL=32
MY has changed between calls.
On intermediate entry, MY=value.
On initial entry, MY=value.
IFAIL=61
On entry, LDLX=value and MX=value.
Constraint: LDLX=0 or LDLX≥MX.
IFAIL=81
On entry, LDLY=value and MY=value.
Constraint: LDLY≥MY.
IFAIL=111
On entry, LDST=value and MX=value.
Constraint: LDST≥MX.
IFAIL=121
On entry, augmented sigma points requested, N=value and MX=value.
Constraint: N≥value.
IFAIL=122
On entry, redrawn sigma points requested, N=value and MX=value.
Constraint: N≥value.
IFAIL=123
N has changed between calls.
On intermediate entry, N=value.
On intermediate exit, N=value.
IFAIL=141
On entry, LDXT=value and MX=value.
Constraint: LDXT≥MX.
IFAIL=161
On entry, LDFXT=value and MX=value.
Constraint: if IREVCM=1, LDFXT≥MX.
IFAIL=162
On entry, LDFXT=value and MY=value.
Constraint: if IREVCM=2, LDFXT≥MY.
IFAIL=171
On entry, ROPT 1=value.
Constraint: ROPT 1=1 or 2.
IFAIL=172
On entry, ROPT value=value.
Constraint: κ>value.
IFAIL=173
On entry, ROPT value=value.
Constraint: α>0.
IFAIL=181
On entry, LROPT=value.
Constraint: 0≤LROPT≤7.
IFAIL=191
ICOMM has been corrupted between calls.
IFAIL=201
On entry, LICOMM=value.
Constraint: LICOMM≥2.
ICOMM is too small to return the required array sizes.
IFAIL=202
On entry, LICOMM=value and LRCOMM=value.
Constraint: LICOMM≥30 and LRCOMM≥30+MY+MX×MY+2×max MX,MY.
The minimum required values for LICOMM and LRCOMM are returned in ICOMM 1 and ICOMM 2 respectively.
IFAIL=211
RCOMM has been corrupted between calls.
IFAIL=301
A weight was negative and it was not possible to downdate the Cholesky factorization.
IFAIL=302
Unable to calculate the Kalman gain matrix.
IFAIL=303
Unable to calculate the Cholesky factorization of the updated state covariance matrix.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

G13EJF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

As well as implementing the Unscented Kalman Filter, G13EJF can also be used to apply the Unscented Transform (see Julier (2002)) to the function F, by setting LDLX=0 and terminating the calling sequence when IREVCM=2 rather than IREVCM=3. In this situation, on initial entry, X and ST would hold the mean and Cholesky factorization of the covariance matrix of the untransformed sample and on exit (when IREVCM=2) they would hold the mean and Cholesky factorization of the covariance matrix of the transformed sample.

10 Example

This example implements the following nonlinear state space model, with the state vector x and state update function F given by:
mx =3 x t+1 = ξ t+1 η t+1 θ t+1 T =F xt+vt = xt+ cos⁡θt -sin⁡θt 0 sin⁡θt cos⁡θt 0 001 0.5⁢r 0.5⁢r 00 r/d -r/d ϕ Rt ϕ Lt +vt
where r and d are known constants and ϕ Rt and ϕ Lt are time-dependent knowns. The measurement vector y and measurement function H is given by:
my =2 yt =δt,αt T =H xt+ut = Δ-ξt⁢cos⁡A-ηt⁢sin⁡A θt-A +ut
where A and Δ are known constants. The initial values, x 0 and P 0, are given by
x 0 = 0 0 0 , P 0 = 0.100 00.10 000.1
and the Cholesky factorizations of the error covariance matrices, Lx and Lx by
L x = 0.100 00.10 000.1 , L y = 0.010 00.01 .

10.1 Program Text

Program Text (g13ejfe.f90)

10.2 Program Data

Program Data (g13ejfe.d)

10.3 Program Results

Program Results (g13ejfe.r)

The example described above can be thought of as relating to the movement of a hypothetical robot. The unknown state, x, is the position of the robot (with respect to a reference frame) and facing, with ξ,η giving the x and y coordinates and θ the angle (with respect to the x-axis) that the robot is facing. The robot has two drive wheels, of radius r on an axle of length d. During time period t the right wheel is believed to rotate at a velocity of ϕ Rt and the left at a velocity of ϕ Lt. In this example, these velocities are fixed with ϕ Rt=0.4 and ϕ Lt=0.1. The state update function, F, calculates where the robot should be at each time point, given its previous position. However, in reality, there is some random fluctuation in the velocity of the wheels, for example, due to slippage. Therefore the actual position of the robot and the position given by equation F will differ.
In the area that the robot is moving there is a single wall. The position of the wall is known and defined by its distance, Δ, from the origin and its angle, A, from the x-axis. The robot has a sensor that is able to measure y, with δ being the distance to the wall and α the angle to the wall. The measurement function H gives the expected distance and angle to the wall if the robot's position is given by xt. Therefore the state space model allows the robot to incorporate the sensor information to update the estimate of its position.
GnuplotProduced by GNUPLOT 4.6 patchlevel 3 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 Example Program Illustration of Position and Orientation of Hypothetical Robot Wall Position gnuplot_plot_1 Initial gnuplot_plot_2 Actual gnuplot_plot_3 Updated gnuplot_plot_4 gnuplot_plot_5 gnuplot_plot_6 gnuplot_plot_7
G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13EKF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13EKF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
▸▿ 3 Description
3.1 Unscented Kalman Filter Algorithm
3.2 Sigma Points
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13EKF applies the Unscented Kalman Filter (UKF) to a nonlinear state space model, with additive noise.
G13EKF uses direct communication for evaluating the nonlinear functionals of the state space model.

2 Specification

SUBROUTINE G13EKF ( MX, MY, Y, LX, LY, F, H, X, ST, IUSER, RUSER, IFAIL)
INTEGER | MX, MY, IUSER(*), IFAIL
REAL (KIND=nag_wp) | Y(MY), LX(MX,MX), LY(MY,MY), X(MX), ST(MX,MX), RUSER(*)
EXTERNAL | F, H

3 Description

G13EKF applies the Unscented Kalman Filter (UKF), as described in Julier and Uhlmann (1997b) to a nonlinear state space model, with additive noise, which, at time t, can be described by:
x t+1 =F xt+vt yt =H xt+ut
where xt represents the unobserved state vector of length mx and yt the observed measurement vector of length my. The process noise is denoted vt, which is assumed to have mean zero and covariance structure Σx, and the measurement noise by ut, which is assumed to have mean zero and covariance structure Σy.

3.1 Unscented Kalman Filter Algorithm

Given x^0, an initial estimate of the state and P 0 and initial estimate of the state covariance matrix, the UKF can be described as follows:
(a) Generate a set of sigma points (see Section 3.2):
Xt = x ^ t-1 x ^ t-1 + γ ⁢ P t-1 x ^ t-1 - γ ⁢ P t-1 (1)
(b) Evaluate the known model function F:
Ft =F Xt (2)
The function F is assumed to accept the mx×n matrix, Xt and return an mx×n matrix, Ft. The columns of both Xt and Ft correspond to different possible states. The notation F t,i is used to denote the ith column of Ft, hence the result of applying F to the ith possible state.
(c) Time Update:
x^t_ | = ∑ i=1 n Wim ⁢ F t,i | (3)
Pt_ | = ∑ i=1 n Wic ⁢ F t,i - x ^ t _ ⁢ F t,i - x ^ t _ T + Σx | (4)
(d) Redraw another set of sigma points (see Section 3.2):
Yt = x ^ t _ x ^ t _ + γ ⁢ Pt_ x ^ t _ - γ ⁢ Pt_ (5)
(e) Evaluate the known model function H:
Ht =H Yt (6)
The function H is assumed to accept the mx×n matrix, Yt and return an my×n matrix, Ht. The columns of both Yt and Ht correspond to different possible states. As above H t,i is used to denote the ith column of Ht.
(f) Measurement Update:
y ^ t | = ∑ i=1 n Wim ⁢ H t,i | (7)
P y yt | = ∑ i=1 n Wic ⁢ H t,i - y ^ t ⁢ H t,i - y ^ t T + Σy | (8)
P x yt | = ∑ i=1 n Wic ⁢ F t,i - x ^ t _ ⁢ H t,i - y ^ t T | (9)
Kt | = P x yt P y yt-1 | (10)
x^t | = x ^ t _ + Kt ⁢ yt - y ^ t | (11)
Pt | = Pt_ - Kt ⁢ P y yt KtT | (12)
Here Kt is the Kalman gain matrix, x^t is the estimated state vector at time t and Pt the corresponding covariance matrix. Rather than implementing the standard UKF as stated above G13EKF uses the square-root form described in the Haykin (2001).

3.2 Sigma Points

A nonlinear state space model involves propagating a vector of random variables through a nonlinear system and we are interested in what happens to the mean and covariance matrix of those variables. Rather than trying to directly propagate the mean and covariance matrix, the UKF uses a set of carefully chosen sample points, referred to as sigma points, and propagates these through the system of interest. An estimate of the propagated mean and covariance matrix is then obtained via the weighted sample mean and covariance matrix.
For a vector of m random variables, x, with mean μ and covariance matrix Σ, the sigma points are usually constructed as:
Xt = μ μ + γ ⁢ Σ μ - γ ⁢ Σ
When calculating the weighted sample mean and covariance matrix two sets of weights are required, one used when calculating the weighted sample mean, denoted Wm and one used when calculated the weighted sample covariance matrix, denoted Wc. The weights and multiplier, γ, are constructed as follows:
λ =α 2⁢L+κ-L γ =L+λ W i m = λ L+λ      i=1 1 2⁢L+λ      i=2,3,…,2⁢L+1 W i c = λ L+λ +1-α 2+β i=1 1 2⁢L+λ i=2,3,…,2⁢L+1
where, usually L=m and α,β and κ are constants. The total number of sigma points, n, is given by 2⁢L+1. The constant α is usually set to somewhere in the range 10-4≤α≤1 and for a Gaussian distribution, the optimal values of κ and β are 3-L and 2 respectively.
The constants, κ, α and β are given by κ=3-mx, α=1.0 and β=2. If more control is required over the construction of the sigma points then the reverse communication routine, G13EJF, can be used instead.

4 References

Haykin S (2001) Kalman Filtering and Neural Networks John Wiley and Sons
Julier S J (2002) The scaled unscented transformation Proceedings of the 2002 American Control Conference (Volume 6) 4555–4559
Julier S J and Uhlmann J K (1997a) A consistent, debiased method for converting between polar and Cartesian coordinate systems Proceedings of AeroSense97, International Society for Optics and Phonotonics 110–121
Julier S J and Uhlmann J K (1997b) A new extension of the Kalman Filter to nonlinear systems International Symposium for Aerospace/Defense, Sensing, Simulation and Controls (Volume 3) 26

5 Arguments

1:   MX – INTEGERInput
On entry: mx, the number of state variables.
Constraint: MX≥1.
2:   MY – INTEGERInput
On entry: my, the number of observed variables.
Constraint: MY≥1.
3:   Y MY – REAL (KIND=nag_wp) arrayInput
On entry: yt, the observed data at the current time point.
4:   LX MXMX – REAL (KIND=nag_wp) arrayInput
On entry: Lx, such that Lx LxT=Σx, i.e., the lower triangular part of a Cholesky decomposition of the process noise covariance structure. Only the lower triangular part of LX is referenced.
If Σx is time dependent, then the value supplied should be for time t.
5:   LY MYMY – REAL (KIND=nag_wp) arrayInput
On entry: Ly, such that Ly LyT=Σy, i.e., the lower triangular part of a Cholesky decomposition of the observation noise covariance structure. Only the lower triangular part of LY is referenced.
If Σy is time dependent, then the value supplied should be for time t.
6:   F – SUBROUTINE, supplied by the user.External Procedure
The state function, F as described in (b).
The specification of F is:
SUBROUTINE F ( MX, N, XT, FXT, IUSER, RUSER, INFO)
INTEGER | MX, N, IUSER(*), INFO
REAL (KIND=nag_wp) | XT(MX,N), FXT(MX,N), RUSER(*)
1:   MX – INTEGERInput
On entry: mx, the number of state variables.
2:   N – INTEGERInput
On entry: n, the number of sigma points.
3:   XT MXN – REAL (KIND=nag_wp) arrayInput
On entry: Xt, the sigma points generated in (a). For the jth sigma point, the value for the ith parameter is held in XT ij, for i=1,2,…,mx and j=1,2,…,n.
4:   FXT MXN – REAL (KIND=nag_wp) arrayOutput
On exit: F Xt .
For the jth sigma point the value for the ith parameter should be held in FXT ij, for i=1,2,…,mx and j=1,2,…,n.
5:   IUSER* – INTEGER arrayUser Workspace
6:   RUSER* – REAL (KIND=nag_wp) arrayUser Workspace
F is called with the arguments IUSER and RUSER as supplied to G13EKF. You are free to use the arrays IUSER and RUSER to supply information to F as an alternative to using COMMON global variables.
7:   INFO – INTEGERInput/Output
On entry: INFO=0.
On exit: set INFO to a nonzero value if you wish G13EKF to terminate with IFAIL=61.
F must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which G13EKF is called. Arguments denoted as Input must not be changed by this procedure.
7:   H – SUBROUTINE, supplied by the user.External Procedure
The measurement function, H as described in (e).
The specification of H is:
SUBROUTINE H ( MX, MY, N, YT, HYT, IUSER, RUSER, INFO)
INTEGER | MX, MY, N, IUSER(*), INFO
REAL (KIND=nag_wp) | YT(MX,N), HYT(MY,N), RUSER(*)
1:   MX – INTEGERInput
On entry: mx, the number of state variables.
2:   MY – INTEGERInput
On entry: my, the number of observed variables.
3:   N – INTEGERInput
On entry: n, the number of sigma points.
4:   YT MXN – REAL (KIND=nag_wp) arrayInput
On entry: Yt, the sigma points generated in (d). For the jth sigma point, the value for the ith parameter is held in YT ij, for i=1,2,…,mx and j=1,2,…,n, where mx is the number of state variables and n is the number of sigma points.
5:   HYT MYN – REAL (KIND=nag_wp) arrayOutput
On exit: H Yt .
For the jth sigma point the value for the ith parameter should be held in HYT ij, for i=1,2,…,my and j=1,2,…,n.
6:   IUSER* – INTEGER arrayUser Workspace
7:   RUSER* – REAL (KIND=nag_wp) arrayUser Workspace
H is called with the arguments IUSER and RUSER as supplied to G13EKF. You are free to use the arrays IUSER and RUSER to supply information to H as an alternative to using COMMON global variables.
8:   INFO – INTEGERInput/Output
On entry: INFO=0.
On exit: set INFO to a nonzero value if you wish G13EKF to terminate with IFAIL=71.
H must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which G13EKF is called. Arguments denoted as Input must not be changed by this procedure.
8:   X MX – REAL (KIND=nag_wp) arrayInput/Output
On entry: x^t-1 the state vector for the previous time point.
On exit: x^t the updated state vector.
9:   ST MXMX – REAL (KIND=nag_wp) arrayInput/Output
On entry: St, such that S t-1 S t-1 T=P t-1, i.e., the lower triangular part of a Cholesky decomposition of the state covariance matrix at the previous time point. Only the lower triangular part of ST is referenced.
On exit: St, the lower triangular part of a Cholesky factorization of the updated state covariance matrix.
10:   IUSER* – INTEGER arrayUser Workspace
11:   RUSER* – REAL (KIND=nag_wp) arrayUser Workspace
IUSER and RUSER are not used by G13EKF, but are passed directly to F and H and may be used to pass information to these routines as an alternative to using COMMON global variables.
12:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=11
On entry, MX=value.
Constraint: MX≥1.
IFAIL=21
On entry, MY=value.
Constraint: MY≥1.
IFAIL=61
User requested termination in F.
IFAIL=71
User requested termination in H.
IFAIL=301
A weight was negative and it was not possible to downdate the Cholesky factorization.
IFAIL=302
Unable to calculate the Kalman gain matrix.
IFAIL=303
Unable to calculate the Cholesky factorization of the updated state covariance matrix.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

G13EKF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

None.

10 Example

This example implements the following nonlinear state space model, with the state vector x and state update function F given by:
mx =3 x t+1 = ξ t+1 η t+1 θ t+1 T =F xt+vt = xt+ cos⁡θt -sin⁡θt 0 sin⁡θt cos⁡θt 0 001 0.5⁢r 0.5⁢r 00 r/d -r/d ϕ Rt ϕ Lt +vt
where r and d are known constants and ϕ Rt and ϕ Lt are time-dependent knowns. The measurement vector y and measurement function H is given by:
my =2 yt =δt,αt T =H xt+ut = Δ-ξt⁢cos⁡A-ηt⁢sin⁡A θt-A +ut
where A and Δ are known constants. The initial values, x 0 and P 0, are given by
x 0 = 0 0 0 , P 0 = 0.100 00.10 000.1
and the Cholesky factorizations of the error covariance matrices, Lx and Lx by
L x = 0.100 00.10 000.1 , L y = 0.010 00.01

10.1 Program Text

Program Text (g13ekfe.f90)

10.2 Program Data

Program Data (g13ekfe.d)

10.3 Program Results

Program Results (g13ekfe.r)

The example described above can be thought of relating to the movement of a hypothetical robot. The unknown state, x, is the position of the robot (with respect to a reference frame) and facing, with ξ,η giving the x and y coordinates and θ the angle (with respect to the x-axis) that the robot is facing. The robot has two drive wheels, of radius r on an axle of length d. During time period t the right wheel is believed to rotate at a velocity of ϕ Rt and the left at a velocity of ϕ Lt. In this example, these velocities are fixed with ϕ Rt=0.4 and ϕ Lt=0.1. The state update function, F, calculates where the robot should be at each time point, given its previous position. However, in reality, there is some random fluctuation in the velocity of the wheels, for example, due to slippage. Therefore the actual position of the robot and the position given by equation F will differ.
In the area that the robot is moving there is a single wall. The position of the wall is known and defined by its distance, Δ, from the origin and its angle, A, from the x-axis. The robot has a sensor that is able to measure y, with δ being the distance to the wall and α the angle to the wall. The measurement function H gives the expected distance and angle to the wall if the robot's position is given by xt. Therefore the state space model allows the robot to incorporate the sensor information to update the estimate of its position.
GnuplotProduced by GNUPLOT 4.6 patchlevel 3 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 Example Program Illustration of Position and Orientation of a Hypothetical Robot Wall Position gnuplot_plot_1 Initial gnuplot_plot_2 Actual gnuplot_plot_3 Updated gnuplot_plot_4 gnuplot_plot_5 gnuplot_plot_6 gnuplot_plot_7
G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13FAF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13FAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13FAF estimates the parameters of either a standard univariate regression GARCH process, or a univariate regression-type I AGARCH p,q process (see Engle and Ng (1993)).

2 Specification

SUBROUTINE G13FAF ( DIST, YT, X, LDX, NUM, IP, IQ, NREG, MN, ISYM, NPAR, THETA, SE, SC, COVR, LDCOVR, HP, ET, HT, LGF, COPTS, MAXIT, TOL, WORK, LWORK, IFAIL)
INTEGER | LDX, NUM, IP, IQ, NREG, MN, ISYM, NPAR, LDCOVR, MAXIT, LWORK, IFAIL
REAL (KIND=nag_wp) | YT(NUM), X(LDX,*), THETA(NPAR), SE(NPAR), SC(NPAR), COVR(LDCOVR,NPAR), HP, ET(NUM), HT(NUM), LGF, TOL, WORK(LWORK)
LOGICAL | COPTS(2)
CHARACTER(1) | DIST

3 Description

A univariate regression-type I AGARCH p,q process, with q coefficients αi, for i=1,2,…,q, p coefficients βi, for i=1,2,…,p, and k linear regression coefficients bi, for i=1,2,…,k, can be represented by:
yt = bo + xtT b + εt (1)
ht=α 0+∑i=1 q αi ε t-i+γ 2+∑i=1 p βih t-i,  t=1,2,…,T (2)
where εt∣ψ t-1=N 0,ht or εt∣ψ t-1=St df,ht. Here St is a standardized Student's t-distribution with df degrees of freedom and variance ht, T is the number of terms in the sequence, yt denotes the endogenous variables, xt the exogenous variables, bo the regression mean, b the regression coefficients, εt the residuals, ht the conditional variance, df the number of degrees of freedom of the Student's t-distribution, and ψt the set of all information up to time t.
G13FAF provides an estimate for θ^, the parameter vector θ=bo,bT,ωT where bT=b 1,…,bk, ωT=α 0,α 1,…,αq,β 1,…,βp,γ when DIST='N' and ωT=α 0,α 1,…,αq,β 1,…,βp,γ,df when DIST='T'.
ISYM, MN and NREG can be used to simplify the GARCH p,q expression in (1) as follows:
No Regression and No Mean
  • yt=εt,
  • ISYM=0,
  • MN=0,
  • NREG=0 and
  • θ is a p+q+1 vector when DIST='N' and a p+q+2 vector when DIST='T'.
No Regression
  • yt=bo+εt,
  • ISYM=0,
  • MN=1,
  • NREG=0 and
  • θ is a p+q+2 vector when DIST='N' and a p+q+3 vector when DIST='T'.
Note: if the yt=μ+εt, where μ is known (not to be estimated by G13FAF) then (1) can be written as ytμ=εt, where ytμ=yt-μ. This corresponds to the case No Regression and No Mean, with yt replaced by yt-μ.
No Mean
  • yt = xtT b + εt ,
  • ISYM=0,
  • MN=0,
  • NREG=k and
  • θ is a p+q+k+1 vector when DIST='N' and a p+q+k+2 vector when DIST='T'.

4 References

Bollerslev T (1986) Generalised autoregressive conditional heteroskedasticity Journal of Econometrics 31 307–327
Engle R (1982) Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation Econometrica 50 987–1008
Engle R and Ng V (1993) Measuring and testing the impact of news on volatility Journal of Finance 48 1749–1777
Hamilton J (1994) Time Series Analysis Princeton University Press

5 Arguments

1:   DIST – CHARACTER(1)Input
On entry: the type of distribution to use for et.
DIST='N'
A Normal distribution is used.
DIST='T'
A Student's t-distribution is used.
Constraint: DIST='N' or 'T'.
2:   YT NUM – REAL (KIND=nag_wp) arrayInput
On entry: the sequence of observations, yt, for t=1,2,…,T.
3:   X LDX* – REAL (KIND=nag_wp) arrayInput
Note: the second dimension of the array X must be at least NREG.
On entry: row t of X must contain the time dependent exogenous vector xt , where xtT = xt 1,…,xtk , for t=1,2,…,T.
4:   LDX – INTEGERInput
On entry: the first dimension of the array X as declared in the (sub)program from which G13FAF is called.
Constraint: LDX≥NUM.
5:   NUM – INTEGERInput
On entry: T, the number of terms in the sequence.
Constraints:
  • NUM≥max IP,IQ;
  • NUM≥NREG+MN.
6:   IP – INTEGERInput
On entry: the number of coefficients, βi, for i=1,2,…,p.
Constraint: IP≥0 (see also NPAR).
7:   IQ – INTEGERInput
On entry: the number of coefficients, αi, for i=1,2,…,q.
Constraint: IQ≥1 (see also NPAR).
8:   NREG – INTEGERInput
On entry: k, the number of regression coefficients.
Constraint: NREG≥0 (see also NPAR).
9:   MN – INTEGERInput
On entry: if MN=1, the mean term b 0 will be included in the model.
Constraint: MN=0 or 1.
10:   ISYM – INTEGERInput
On entry: if ISYM=1, the asymmetry term γ will be included in the model.
Constraint: ISYM=0 or 1.
11:   NPAR – INTEGERInput
On entry: the number of parameters to be included in the model. NPAR=1+IQ+IP+ISYM+MN+NREG when DIST='N', and NPAR=2+IQ+IP+ISYM+MN+NREG when DIST='T'.
Constraint: NPAR<20.
12:   THETA NPAR – REAL (KIND=nag_wp) arrayInput/Output
On entry: the initial parameter estimates for the vector θ.
The first element must contain the coefficient αo and the next IQ elements must contain the coefficients αi, for i=1,2,…,q.
The next IP elements must contain the coefficients βj, for j=1,2,…,p.
If ISYM=1, the next element must contain the asymmetry parameter γ.
If DIST='T', the next element must contain df, the number of degrees of freedom of the Student's t-distribution.
If MN=1, the next element must contain the mean term bo.
If COPTS 2=.FALSE., the remaining NREG elements are taken as initial estimates of the linear regression coefficients bi, for i=1,2,…,k.
On exit: the estimated values θ^ for the vector θ.
The first element contains the coefficient αo, the next IQ elements contain the coefficients αi, for i=1,2,…,q.
The next IP elements are the coefficients βj, for j=1,2,…,p.
If ISYM=1, the next element contains the estimate for the asymmetry parameter γ.
If DIST='T', the next element contains an estimate for df, the number of degrees of freedom of the Student's t-distribution.
If MN=1, the next element contains an estimate for the mean term bo.
The final NREG elements are the estimated linear regression coefficients bi, for i=1,2,…,k.
13:   SE NPAR – REAL (KIND=nag_wp) arrayOutput
On exit: the standard errors for θ^.
The first element contains the standard error for αo. The next IQ elements contain the standard errors for αi, for i=1,2,…,q. The next IP elements are the standard errors for βj, for j=1,2,…,p.
If ISYM=1, the next element contains the standard error for γ.
If DIST='T', the next element contains the standard error for df, the number of degrees of freedom of the Student's t-distribution.
If MN=1, the next element contains the standard error for bo.
The final NREG elements are the standard errors for bj, for j=1,2,…,k.
14:   SC NPAR – REAL (KIND=nag_wp) arrayOutput
On exit: the scores for θ^.
The first element contains the score for αo.
The next IQ elements contain the score for αi, for i=1,2,…,q.
The next IP elements are the scores for βj, for j=1,2,…,p.
If ISYM=1, the next element contains the score for γ.
If DIST='T', the next element contains the score for df, the number of degrees of freedom of the Student's t-distribution.
If MN=1, the next element contains the score for bo.
The final NREG elements are the scores for bj, for j=1,2,…,k.
15:   COVR LDCOVRNPAR – REAL (KIND=nag_wp) arrayOutput
On exit: the covariance matrix of the parameter estimates θ^, that is the inverse of the Fisher Information Matrix.
16:   LDCOVR – INTEGERInput
On entry: the first dimension of the array COVR as declared in the (sub)program from which G13FAF is called.
Constraint: LDCOVR≥NPAR.
17:   HP – REAL (KIND=nag_wp)Input/Output
On entry: if COPTS 2=.FALSE., HP is the value to be used for the pre-observed conditional variance; otherwise HP is not referenced.
On exit: if COPTS 2=.TRUE., HP is the estimated value of the pre-observed conditional variance.
18:   ET NUM – REAL (KIND=nag_wp) arrayOutput
On exit: the estimated residuals, εt, for t=1,2,…,T.
19:   HT NUM – REAL (KIND=nag_wp) arrayOutput
On exit: the estimated conditional variances, ht, for t=1,2,…,T.
20:   LGF – REAL (KIND=nag_wp)Output
On exit: the value of the log-likelihood function at θ^.
21:   COPTS 2 – LOGICAL arrayInput
On entry: the options to be used by G13FAF.
COPTS 1=.TRUE.
Stationary conditions are enforced, otherwise they are not.
COPTS 2=.TRUE.
The routine provides initial parameter estimates of the regression terms, otherwise these are to be provided by you.
22:   MAXIT – INTEGERInput
On entry: the maximum number of iterations to be used by the optimization routine when estimating the GARCH p,q parameters. If MAXIT is set to 0, the standard errors, score vector and variance-covariance are calculated for the input value of θ in THETA when DIST='N'; however the value of θ is not updated.
Constraint: MAXIT≥0.
23:   TOL – REAL (KIND=nag_wp)Input
On entry: the tolerance to be used by the optimization routine when estimating the GARCH p,q parameters.
24:   WORK LWORK – REAL (KIND=nag_wp) arrayWorkspace
25:   LWORK – INTEGERInput
On entry: the dimension of the array WORK as declared in the (sub)program from which G13FAF is called.
Constraint: LWORK≥NREG+3×NUM+NPAR+403.
26:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if IFAIL≠0 on exit, the recommended value is -1. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Note: G13FAF may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the routine:
IFAIL=1
On entry, | NREG<0,
or | MN>1,
or | MN<0,
or | ISYM>1,
or | ISYM<0,
or | IQ<1,
or | IP<0,
or | NPAR≥20,
or | NPAR has an invalid value,
or | LDCOVR<NPAR,
or | LDX<NUM,
or | DIST≠'N',
or | DIST≠'T',
or | MAXIT<0,
or | NUM<max IP,IQ,
or | NUM<NREG+MN.
IFAIL=2
On entry, LWORK<NREG+3×NUM+NPAR+403.
IFAIL=3
The matrix X is not full rank.
IFAIL=4
The information matrix is not positive definite.
IFAIL=5
The maximum number of iterations has been reached.
IFAIL=6
The log-likelihood cannot be optimized any further.
IFAIL=7
No feasible model parameters could be found.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

G13FAF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13FAF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

None.

10 Example

This example fits a GARCH 1,1 model with Student's t-distributed residuals to some simulated data.
The process parameter estimates, θ^, are obtained using G13FAF, and a four step ahead volatility estimate is computed using G13FBF.
The data was simulated using G05PDF.

10.1 Program Text

Program Text (g13fafe.f90)

10.2 Program Data

Program Data (g13fafe.d)

10.3 Program Results

Program Results (g13fafe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13FBF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13FBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

G13FBF forecasts the conditional variances ht, for t=T+1,…,T+ξ, from a type I AGARCH p,q sequence, where ξ is the forecast horizon and T is the current time (see Engle and Ng (1993)).

2 Specification

SUBROUTINE G13FBF ( NUM, NT, IP, IQ, THETA, GAMMA, FHT, HT, ET, IFAIL)
INTEGER | NUM, NT, IP, IQ, IFAIL
REAL (KIND=nag_wp) | THETA(IQ+IP+1), GAMMA, FHT(NT), HT(NUM), ET(NUM)

3 Description

Assume the GARCH p,q process can be represented by:
ht=α 0+∑i=1 q αi ε t-i+γ 2+∑i=1 p βih t-i,  t=1,2,…,T
where εt∣ψ t-1=N 0,ht or εt∣ψ t-1=St df,ht, has been modelled by G13FAF and the estimated conditional variances and residuals are contained in the arrays HT and ET respectively.
G13FBF will then use the last max p,q elements of the arrays HT and ET to estimate the conditional variance forecasts, ht∣ψT, where t=T+1,…,T+ξ and ξ is the forecast horizon.

4 References

Bollerslev T (1986) Generalised autoregressive conditional heteroskedasticity Journal of Econometrics 31 307–327
Engle R (1982) Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation Econometrica 50 987–1008
Engle R and Ng V (1993) Measuring and testing the impact of news on volatility Journal of Finance 48 1749–1777
Hamilton J (1994) Time Series Analysis Princeton University Press

5 Arguments

1:   NUM – INTEGERInput
On entry: the number of terms in the arrays HT and ET from the modelled sequence.
Constraint: max IP,IQ≤NUM.
2:   NT – INTEGERInput
On entry: ξ, the forecast horizon.
Constraint: NT>0.
3:   IP – INTEGERInput
On entry: the number of coefficients, βi, for i=1,2,…,p.
Constraints:
  • max IP,IQ≤20;
  • IP≥0.
4:   IQ – INTEGERInput
On entry: the number of coefficients, αi, for i=1,2,…,q.
Constraints:
  • max IP,IQ≤20;
  • IQ≥1.
5:   THETA IQ+IP+1 – REAL (KIND=nag_wp) arrayInput
On entry: the first element must contain the coefficient αo and the next IQ elements must contain the coefficients αi, for i=1,2,…,q. The remaining IP elements must contain the coefficients βj, for j=1,2,…,p.
6:   GAMMA – REAL (KIND=nag_wp)Input
On entry: the asymmetry parameter γ for the GARCH p,q sequence.
7:   FHT NT – REAL (KIND=nag_wp) arrayOutput
On exit: the forecast values of the conditional variance, ht, for t=T+1,…,T+ξ.
8:   HT NUM – REAL (KIND=nag_wp) arrayInput
On entry: the sequence of past conditional variances for the GARCH p,q process, ht, for t=1,2,…,T.
9:   ET NUM – REAL (KIND=nag_wp) arrayInput
On entry: the sequence of past residuals for the GARCH p,q process, εt, for t=1,2,…,T.
10:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | NUM<max IP,IQ,
or | IQ<1,
or | IP<0,
or | max IP,IQ>20,
or | NT≤0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

G13FBF is not threaded in any implementation.

9 Further Comments

None.

10 Example

See Section 10 in G13FAF.
G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13FCF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13FCF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13FCF estimates the parameters of a univariate regression-type II AGARCH p,q process.

2 Specification

SUBROUTINE G13FCF ( DIST, YT, X, LDX, NUM, IP, IQ, NREG, MN, NPAR, THETA, SE, SC, COVR, LDCOVR, HP, ET, HT, LGF, COPTS, MAXIT, TOL, WORK, LWORK, IFAIL)
INTEGER | LDX, NUM, IP, IQ, NREG, MN, NPAR, LDCOVR, MAXIT, LWORK, IFAIL
REAL (KIND=nag_wp) | YT(NUM), X(LDX,*), THETA(NPAR), SE(NPAR), SC(NPAR), COVR(LDCOVR,NPAR), HP, ET(NUM), HT(NUM), LGF, TOL, WORK(LWORK)
LOGICAL | COPTS(2)
CHARACTER(1) | DIST

3 Description

A univariate regression-type II AGARCH p,q process, with q coefficients αi, for i=1,2,…,q, p coefficients, βi, for i=1,2,…,p, and k linear regression coefficients bi, for i=1,2,…,k, can be represented by:
yt = bo + xtT b + εt (1)
ht=α 0+∑i=1 q αi ε t-i+γ ε t-i 2+∑i=1 p βih t-i,  t=1,2,…,T. (2)
where εt∣ψ t-1=N 0,ht or εt∣ψ t-1=St df,ht. Here St is a standardized Student's t-distribution with df degrees of freedom and variance ht, T is the number of terms in the sequence, yt denotes the endogenous variables, xt the exogenous variables, bo the regression mean, b the regression coefficients, εt the residuals, ht the conditional variance, and ψt the set of all information up to time t.
G13FCF provides an estimate for the parameter vector θ=bo,bT,ωT where bT=b 1,…,bk, ωT=α 0,α 1,…,αq,β 1,…,βp,γ when DIST='N' and ωT=α 0,α 1,…,αq,β 1,…,βp,γ,df when DIST='T'.
MN and NREG can be used to simplify the GARCH p,q expression in (1) as follows:
No Regression and No Mean
  • yt=εt,
  • MN=0,
  • NREG=0 and
  • θ is a p+q+2 vector when DIST='N' and a p+q+3 vector when DIST='T'.
No Regression
  • yt=bo+εt,
  • MN=1,
  • NREG=0 and
  • θ is a p+q+3 vector when DIST='N' and a p+q+4×1 vector when DIST='T'.
Note: if the yt=μ+εt, where μ is known (not to be estimated by G13FCF) then (1) can be written as ytμ=εt, where ytμ=yt-μ. This corresponds to the case No Regression and No Mean, with yt replaced by yt-μ.
No Mean
  • yt = xtT b + εt ,
  • MN=0,
  • NREG=k and
  • θ is a p+q+k+2 vector when DIST='N' and a p+q+k+3 vector when DIST='T'.

4 References

Bollerslev T (1986) Generalised autoregressive conditional heteroskedasticity Journal of Econometrics 31 307–327
Engle R (1982) Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation Econometrica 50 987–1008
Engle R and Ng V (1993) Measuring and testing the impact of news on volatility Journal of Finance 48 1749–1777
Hamilton J (1994) Time Series Analysis Princeton University Press

5 Arguments

1:   DIST – CHARACTER(1)Input
On entry: the type of distribution to use for et.
DIST='N'
A Normal distribution is used.
DIST='T'
A Student's t-distribution is used.
Constraint: DIST='N' or 'T'.
2:   YT NUM – REAL (KIND=nag_wp) arrayInput
On entry: the sequence of observations, yt, for t=1,2,…,T.
3:   X LDX* – REAL (KIND=nag_wp) arrayInput
Note: the second dimension of the array X must be at least NREG.
On entry: row t of X must contain the time dependent exogenous vector xt , where xtT = xt 1,…,xtk , for t=1,2,…,T.
4:   LDX – INTEGERInput
On entry: the first dimension of the array X as declared in the (sub)program from which G13FCF is called.
Constraint: LDX≥NUM.
5:   NUM – INTEGERInput
On entry: T, the number of terms in the sequence.
Constraints:
  • NUM≥max IP,IQ;
  • NUM≥NREG+MN.
6:   IP – INTEGERInput
On entry: the number of coefficients, βi, for i=1,2,…,p.
Constraint: IP≥0 (see also NPAR).
7:   IQ – INTEGERInput
On entry: the number of coefficients, αi, for i=1,2,…,q.
Constraint: IQ≥1 (see also NPAR).
8:   NREG – INTEGERInput
On entry: k, the number of regression coefficients.
Constraint: NREG≥0 (see also NPAR).
9:   MN – INTEGERInput
On entry: if MN=1, the mean term b 0 will be included in the model.
Constraint: MN=0 or 1.
10:   NPAR – INTEGERInput
On entry: the number of parameters to be included in the model. NPAR=2+IQ+IP+MN+NREG when DIST='N' and NPAR=3+IQ+IP+MN+NREG when DIST='T'.
Constraint: NPAR<20.
11:   THETA NPAR – REAL (KIND=nag_wp) arrayInput/Output
On entry: the initial parameter estimates for the vector θ.
The first element must contain the coefficient αo and the next IQ elements must contain the coefficients αi, for i=1,2,…,q.
The next IP elements must contain the coefficients βj, for j=1,2,…,p.
The next element must contain the asymmetry parameter γ.
If DIST='T', the next element must contain df, the number of degrees of freedom of the Student's t-distribution.
If MN=1, the next element contains the mean term bo.
If COPTS 2=.FALSE., the remaining NREG elements are taken as initial estimates of the linear regression coefficients bi, for i=1,2,…,k.
On exit: the estimated values θ^ for the vector θ.
The first element contains the coefficient αo, the next IQ elements contain the coefficients αi, for i=1,2,…,q.
The next IP elements are the coefficients βj, for j=1,2,…,p.
The next element contains the estimate for the asymmetry parameter γ.
If DIST='T', the next element contains an estimate for df, the number of degrees of freedom of the Student's t-distribution.
If MN=1, the next element contains an estimate for the mean term bo.
The final NREG elements are the estimated linear regression coefficients bi, for i=1,2,…,k.
12:   SE NPAR – REAL (KIND=nag_wp) arrayOutput
On exit: the standard errors for θ^.
The first element contains the standard error for αo and the next IQ elements contain the standard errors for αi, for i=1,2,…,q.
The next IP elements are the standard errors for βj, for j=1,2,…,p.
The next element contains the standard error for γ.
If DIST='T', the next element contains the standard error for df, the number of degrees of freedom of the Student's t-distribution.
If MN=1, the next element contains the standard error for bo.
The final NREG elements are the standard errors for bj, for j=1,2,…,k.
13:   SC NPAR – REAL (KIND=nag_wp) arrayOutput
On exit: the scores for θ^.
The first element contains the score for αo and the next IQ elements contain the score for αi, for i=1,2,…,q.
The next IP elements are the scores for βj, for j=1,2,…,p.
The next element contains the score for γ.
If DIST='T', the next element contains the score for df, the number of degrees of freedom of the Student's t-distribution.
If MN=1, the next element contains the score for bo.
The final NREG elements are the scores for bj, for j=1,2,…,k.
14:   COVR LDCOVRNPAR – REAL (KIND=nag_wp) arrayOutput
On exit: the covariance matrix of the parameter estimates θ^, that is the inverse of the Fisher Information Matrix.
15:   LDCOVR – INTEGERInput
On entry: the first dimension of the array COVR as declared in the (sub)program from which G13FCF is called.
Constraint: LDCOVR≥NPAR.
16:   HP – REAL (KIND=nag_wp)Input/Output
On entry: if COPTS 2=.FALSE., HP is the value to be used for the pre-observed conditional variance; otherwise HP is not referenced.
On exit: if COPTS 2=.TRUE., HP is the estimated value of the pre-observed conditional variance.
17:   ET NUM – REAL (KIND=nag_wp) arrayOutput
On exit: the estimated residuals, εt, for t=1,2,…,T.
18:   HT NUM – REAL (KIND=nag_wp) arrayOutput
On exit: the estimated conditional variances, ht, for t=1,2,…,T.
19:   LGF – REAL (KIND=nag_wp)Output
On exit: the value of the log-likelihood function at θ^.
20:   COPTS 2 – LOGICAL arrayInput
On entry: the options to be used by G13FCF.
COPTS 1=.TRUE.
Stationary conditions are enforced, otherwise they are not.
COPTS 2=.TRUE.
The routine provides initial parameter estimates of the regression terms, otherwise these are to be provided by you.
21:   MAXIT – INTEGERInput
On entry: the maximum number of iterations to be used by the optimization routine when estimating the GARCH p,q parameters. If MAXIT is set to 0, the standard errors, score vector and variance-covariance are calculated for the input value of θ in THETA when DIST='N'; however the value of θ is not updated.
Constraint: MAXIT≥0.
22:   TOL – REAL (KIND=nag_wp)Input
On entry: the tolerance to be used by the optimization routine when estimating the GARCH p,q parameters.
23:   WORK LWORK – REAL (KIND=nag_wp) arrayWorkspace
24:   LWORK – INTEGERInput
On entry: the dimension of the array WORK as declared in the (sub)program from which G13FCF is called.
Constraint: LWORK≥NREG+3×NUM+NPAR+403.
25:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if IFAIL≠0 on exit, the recommended value is -1. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Note: G13FCF may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the routine:
IFAIL=1
On entry, | NREG<0,
or | MN>1,
or | MN<0,
or | IQ<1,
or | IP<0,
or | NPAR≥20,
or | LDCOVR<NPAR,
or | LDX<NUM,
or | DIST≠'N', and DIST≠'T',
or | MAXIT<0,
or | NUM<NREG+MN,
or | NPAR has an invalid value NUM<max IP,IQ.
IFAIL=2
On entry, LWORK<NREG+3×NUM+3.
IFAIL=3
The matrix X is not full rank.
IFAIL=4
The information matrix is not positive definite.
IFAIL=5
The maximum number of iterations has been reached.
IFAIL=6
The log-likelihood cannot be optimized any further.
IFAIL=7
No feasible model parameters could be found.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

G13FCF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13FCF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

None.

10 Example

This example fits a GARCH 1,1 model with Student's t-distributed residuals to some simulated data.
The process parameter estimates, θ^, are obtained using G13FCF, and a four step ahead volatility estimate is computed using G13FDF.
The data was simulated using G05PEF.

10.1 Program Text

Program Text (g13fcfe.f90)

10.2 Program Data

Program Data (g13fcfe.d)

10.3 Program Results

Program Results (g13fcfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13FDF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13FDF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

G13FDF forecasts the conditional variances, ht,t=T+1,…,T+ξ from a type II AGARCH p,q sequence, where ξ is the forecast horizon and T is the current time (see Engle and Ng (1993)).

2 Specification

SUBROUTINE G13FDF ( NUM, NT, IP, IQ, THETA, GAMMA, FHT, HT, ET, IFAIL)
INTEGER | NUM, NT, IP, IQ, IFAIL
REAL (KIND=nag_wp) | THETA(IQ+IP+1), GAMMA, FHT(NT), HT(NUM), ET(NUM)

3 Description

Assume the GARCH p,q process can be represented by:
ht=α 0+∑i=1 q αi ε t-i+γ ε t-i 2+∑i=1 p βih t-i,  t=1,2,…,T.
where εt∣ψ t-1=N 0,ht or εt∣ψ t-1=St df,ht, has been modelled by G13FCF and the estimated conditional variances and residuals are contained in the arrays HT and ET respectively.
G13FDF will then use the last max p,q elements of the arrays HT and ET to estimate the conditional variance forecasts, ht∣ψT, where t=T+1,…,T+ξ and ξ is the forecast horizon.

4 References

Bollerslev T (1986) Generalised autoregressive conditional heteroskedasticity Journal of Econometrics 31 307–327
Engle R (1982) Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation Econometrica 50 987–1008
Engle R and Ng V (1993) Measuring and testing the impact of news on volatility Journal of Finance 48 1749–1777
Hamilton J (1994) Time Series Analysis Princeton University Press

5 Arguments

1:   NUM – INTEGERInput
On entry: the number of terms in the arrays HT and ET from the modelled sequence.
Constraint: max IP,IQ≤NUM.
2:   NT – INTEGERInput
On entry: ξ, the forecast horizon.
Constraint: NT>0.
3:   IP – INTEGERInput
On entry: the number of coefficients, βi, for i=1,2,…,p.
Constraints:
  • max IP,IQ≤20;
  • IP≥0.
4:   IQ – INTEGERInput
On entry: the number of coefficients, αi, for i=1,2,…,q.
Constraints:
  • max IP,IQ≤20;
  • IQ≥1.
5:   THETA IQ+IP+1 – REAL (KIND=nag_wp) arrayInput
On entry: the first element must contain the coefficient αo and the next IQ elements must contain the coefficients αi, for i=1,2,…,q. The remaining IP elements must contain the coefficients βj, for j=1,2,…,p.
6:   GAMMA – REAL (KIND=nag_wp)Input
On entry: the asymmetry parameter γ for the GARCH p,q sequence.
7:   FHT NT – REAL (KIND=nag_wp) arrayOutput
On exit: the forecast values of the conditional variance, ht, for t=T+1,…,T+ξ.
8:   HT NUM – REAL (KIND=nag_wp) arrayInput
On entry: the sequence of past conditional variances for the GARCH p,q process, ht, for t=1,2,…,T.
9:   ET NUM – REAL (KIND=nag_wp) arrayInput
On entry: the sequence of past residuals for the GARCH p,q process, εt, for t=1,2,…,T.
10:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | NUM<max IP,IQ,
or | IQ<1,
or | IP<0,
or | max IP,IQ>20,
or | NT≤0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

G13FDF is not threaded in any implementation.

9 Further Comments

None.

10 Example

See Section 10 in G13FCF.
G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13FEF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13FEF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13FEF estimates the parameters of a univariate regression-GJR GARCH p,q process (see Glosten et al. (1993)).

2 Specification

SUBROUTINE G13FEF ( DIST, YT, X, LDX, NUM, IP, IQ, NREG, MN, NPAR, THETA, SE, SC, COVR, LDCOVR, HP, ET, HT, LGF, COPTS, MAXIT, TOL, WORK, LWORK, IFAIL)
INTEGER | LDX, NUM, IP, IQ, NREG, MN, NPAR, LDCOVR, MAXIT, LWORK, IFAIL
REAL (KIND=nag_wp) | YT(NUM), X(LDX,*), THETA(NPAR), SE(NPAR), SC(NPAR), COVR(LDCOVR,NPAR), HP, ET(NUM), HT(NUM), LGF, TOL, WORK(LWORK)
LOGICAL | COPTS(2)
CHARACTER(1) | DIST

3 Description

A univariate regression-GJR GARCH p,q process, with q coefficients αi, for i=1,2,…,q, p coefficients βi, for i=1,2,…,p, and k linear regression coefficients bi, for i=1,2,…,k, can be represented by:
yt = bo + xtT b + εt (1)
ht = α 0 + ∑ i=1 q αi + γ I t-i ε t-i 2 + ∑ i=1 p βi h t-i ,   t=1,2,…,T (2)
where It=1, if εt<0, It=0, if εt≥0, and εt∣ψ t-1=N 0,ht or εt∣ψ t-1=St df,ht. Here St is a standardized Student's t-distribution with df degrees of freedom and variance ht, T is the number of terms in the sequence, yt denotes the endogenous variables, xt the exogenous variables, bo the regression mean, b the regression coefficients, εt the residuals, ht is the conditional variance, and ψt the set of all information up to time t.
G13FEF provides an estimate for θ^, the parameter vector θ=bo,bT,ωT where bT=b 1,…,bk, ωT=α 0,α 1,…,αq,β 1,…,βp,γ when DIST='N' and ωT=α 0,α 1,…,αq,β 1,…,βp,γ,df when DIST='T'.
MN, NREG can be used to simplify the GARCH p,q expression in (1) as follows:
No Regression and No Mean
  • yt=εt,
  • MN=0,
  • NREG=0 and
  • θ is a p+q+2 vector when DIST='N', and a p+q+3 vector when DIST='T'.
No Regression
  • yt=bo+εt,
  • MN=1,
  • NREG=0 and
  • θ is a p+q+3 vector when DIST='N', and a p+q+4 vector when DIST='T'.
Note: if the yt=μ+εt, where μ is known (not to be estimated by G13FEF) then (1) can be written as ytμ=εt, where ytμ=yt-μ. This corresponds to the case No Regression and No Mean, with yt replaced by yt-μ.
No Mean
  • yt = xtT b + εt ,
  • MN=0,
  • NREG=k and
  • θ is a p+q+k+2 vector when DIST='N', and a p+q+k+3 vector when DIST='T'.

4 References

Bollerslev T (1986) Generalised autoregressive conditional heteroskedasticity Journal of Econometrics 31 307–327
Engle R (1982) Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation Econometrica 50 987–1008
Engle R and Ng V (1993) Measuring and testing the impact of news on volatility Journal of Finance 48 1749–1777
Glosten L, Jagannathan R and Runkle D (1993) Relationship between the expected value and the volatility of nominal excess return on stocks Journal of Finance 48 1779–1801
Hamilton J (1994) Time Series Analysis Princeton University Press

5 Arguments

1:   DIST – CHARACTER(1)Input
On entry: the type of distribution to use for et.
DIST='N'
A Normal distribution is used.
DIST='T'
A Student's t-distribution is used.
Constraint: DIST='N' or 'T'.
2:   YT NUM – REAL (KIND=nag_wp) arrayInput
On entry: the sequence of observations, yt, for t=1,2,…,T.
3:   X LDX* – REAL (KIND=nag_wp) arrayInput
Note: the second dimension of the array X must be at least NREG.
On entry: row t of X must contain the time dependent exogenous vector xt , where xtT = xt 1,…,xtk , for t=1,2,…,T.
4:   LDX – INTEGERInput
On entry: the first dimension of the array X as declared in the (sub)program from which G13FEF is called.
Constraint: LDX≥NUM.
5:   NUM – INTEGERInput
On entry: T, the number of terms in the sequence.
Constraints:
  • NUM≥max IP,IQ;
  • NUM≥NREG+MN.
6:   IP – INTEGERInput
On entry: the number of coefficients, βi, for i=1,2,…,p.
Constraint: IP≥0 (see also NPAR).
7:   IQ – INTEGERInput
On entry: the number of coefficients, αi, for i=1,2,…,q.
Constraint: IQ≥1 (see also NPAR).
8:   NREG – INTEGERInput
On entry: k, the number of regression coefficients.
Constraint: NREG≥0 (see also NPAR).
9:   MN – INTEGERInput
On entry: if MN=1, the mean term b 0 will be included in the model.
Constraint: MN=0 or 1.
10:   NPAR – INTEGERInput
On entry: the number of parameters to be included in the model. NPAR=2+IQ+IP+MN+NREG when DIST='N' and NPAR=3+IQ+IP+MN+NREG when DIST='T'.
Constraint: NPAR<20.
11:   THETA NPAR – REAL (KIND=nag_wp) arrayInput/Output
On entry: the initial parameter estimates for the vector θ.
The first element must contain the coefficient αo and the next IQ elements contain the coefficients αi, for i=1,2,…,q.
The next IP elements must contain the coefficients βj, for j=1,2,…,p.
The next element must contain the asymmetry parameter γ.
If DIST='T', the next element contains df, the number of degrees of freedom of the Student's t-distribution.
If MN=1, the next element must contain the mean term bo.
If COPTS 2=.FALSE., the remaining NREG elements are taken as initial estimates of the linear regression coefficients bi, for i=1,2,…,k.
On exit: the estimated values θ^ for the vector θ.
The first element contains the coefficient αo, the next IQ elements contain the coefficients αi, for i=1,2,…,q.
The next IP elements are the moving average coefficients βj, for j=1,2,…,p.
The next element contains the estimate for the asymmetry parameter γ.
If DIST='T', the next element contains an estimate for df, the number of degrees of freedom of the Student's t-distribution.
If MN=1, the next element contains an estimate for the mean term bo.
The final NREG elements are the estimated linear regression coefficients bi, for i=1,2,…,k.
12:   SE NPAR – REAL (KIND=nag_wp) arrayOutput
On exit: the standard errors for θ^.
The first element contains the standard error for αo and the next IQ elements contain the standard errors for αi, for i=1,2,…,q.
The next IP elements are the standard errors for βj, for j=1,2,…,p.
The next element contains the standard error for γ.
If DIST='T', the next element contains the standard error for df, the number of degrees of freedom of the Student's t-distribution.
If MN=1, the next element contains the standard error for bo.
The final NREG elements are the standard errors for bj, for j=1,2,…,k.
13:   SC NPAR – REAL (KIND=nag_wp) arrayOutput
On exit: the scores for θ^.
The first element contains the score for αo, the next IQ elements contain the scores for αi, for i=1,2,…,q.
The next IP elements are the score for βj, for j=1,2,…,p.
The next element contains the score for γ.
If DIST='T', the next element contains the score for df, the number of degrees of freedom of the Student's t-distribution.
If MN=1, the next element contains the score for bo.
The final NREG elements are the scores for bj, for j=1,2,…,k.
14:   COVR LDCOVRNPAR – REAL (KIND=nag_wp) arrayOutput
On exit: the covariance matrix of the parameter estimates θ^, that is the inverse of the Fisher Information Matrix.
15:   LDCOVR – INTEGERInput
On entry: the first dimension of the array COVR as declared in the (sub)program from which G13FEF is called.
Constraint: LDCOVR≥NPAR.
16:   HP – REAL (KIND=nag_wp)Input/Output
On entry: if COPTS 2=.FALSE., HP is the value to be used for the pre-observed conditional variance; otherwise HP is not referenced.
On exit: if COPTS 2=.TRUE., HP is the estimated value of the pre-observed conditional variance.
17:   ET NUM – REAL (KIND=nag_wp) arrayOutput
On exit: the estimated residuals, εt, for t=1,2,…,T.
18:   HT NUM – REAL (KIND=nag_wp) arrayOutput
On exit: the estimated conditional variances, ht, for t=1,2,…,T.
19:   LGF – REAL (KIND=nag_wp)Output
On exit: the value of the log-likelihood function at θ^.
20:   COPTS 2 – LOGICAL arrayInput
On entry: the options to be used by G13FEF.
COPTS 1=.TRUE.
Stationary conditions are enforced, otherwise they are not.
COPTS 2=.TRUE.
The routine provides initial parameter estimates of the regression terms, otherwise these are to be provided by you.
21:   MAXIT – INTEGERInput
On entry: the maximum number of iterations to be used by the optimization routine when estimating the GARCH p,q parameters. If MAXIT is set to 0, the standard errors, score vector and variance-covariance are calculated for the input value of θ in THETA when DIST='N'; however the value of θ is not updated.
Constraint: MAXIT≥0.
22:   TOL – REAL (KIND=nag_wp)Input
On entry: the tolerance to be used by the optimization routine when estimating the GARCH p,q parameters.
23:   WORK LWORK – REAL (KIND=nag_wp) arrayWorkspace
24:   LWORK – INTEGERInput
On entry: the dimension of the array WORK as declared in the (sub)program from which G13FEF is called.
Constraint: LWORK≥NREG+3×NUM+NPAR+403.
25:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if IFAIL≠0 on exit, the recommended value is -1. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Note: G13FEF may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the routine:
IFAIL=1
On entry, | NREG<0,
or | MN>1,
or | MN<0,
or | IQ<1,
or | IP<0,
or | NPAR≥20,
or | NPAR has an invalid value,
or | LDCOVR<NPAR,
or | LDX<NUM,
or | DIST≠'N',
or | DIST≠'T',
or | MAXIT<0,
or | NUM<max IP,IQ,
or | NUM<NREG+MN.
IFAIL=2
On entry, LWORK<NREG+3×NUM+NPAR+403.
IFAIL=3
The matrix X is not full rank.
IFAIL=4
The information matrix is not positive definite.
IFAIL=5
The maximum number of iterations has been reached.
IFAIL=6
The log-likelihood cannot be optimized any further.
IFAIL=7
No feasible model parameters could be found.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

G13FEF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13FEF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

None.

10 Example

This example fits a GARCH 1,1 model with Student's t-distributed residuals to some simulated data.
The process parameter estimates, θ^, are obtained using G13FEF, and a four step ahead volatility estimate is computed using G13FFF.
The data was simulated using G05PFF.

10.1 Program Text

Program Text (g13fefe.f90)

10.2 Program Data

Program Data (g13fefe.d)

10.3 Program Results

Program Results (g13fefe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13FFF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13FFF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

G13FFF forecasts the conditional variances, ht, for t=T+1,…,T+ξ from a GJR GARCH p,q sequence, where ξ is the forecast horizon and T is the current time (see Glosten et al. (1993)).

2 Specification

SUBROUTINE G13FFF ( NUM, NT, IP, IQ, THETA, GAMMA, FHT, HT, ET, IFAIL)
INTEGER | NUM, NT, IP, IQ, IFAIL
REAL (KIND=nag_wp) | THETA(IQ+IP+1), GAMMA, FHT(NT), HT(NUM), ET(NUM)

3 Description

Assume the GARCH p,q process can be represented by:
ht = α 0 + ∑ i=1 q αi + γ I t-i ε t-i 2 + ∑ i=1 p βi h t-i ,   t=1,2,…,T .
where εt∣ψ t-1=N 0,ht or εt∣ψ t-1=St df,ht, and It=1, if εt<0, or It=0, if εt≥0, has been modelled by G13FEF, and the estimated conditional variances and residuals are contained in the arrays HT and ET respectively.
G13FFF will then use the last max p,q elements of the arrays HT and ET to estimate the conditional variance forecasts, ht∣ψT, where t=T+1,…,T+ξ and ξ is the forecast horizon.

4 References

Bollerslev T (1986) Generalised autoregressive conditional heteroskedasticity Journal of Econometrics 31 307–327
Engle R (1982) Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation Econometrica 50 987–1008
Engle R and Ng V (1993) Measuring and testing the impact of news on volatility Journal of Finance 48 1749–1777
Glosten L, Jagannathan R and Runkle D (1993) Relationship between the expected value and the volatility of nominal excess return on stocks Journal of Finance 48 1779–1801
Hamilton J (1994) Time Series Analysis Princeton University Press

5 Arguments

1:   NUM – INTEGERInput
On entry: the number of terms in the arrays HT and ET from the modelled sequence.
Constraint: max IP,IQ≤NUM.
2:   NT – INTEGERInput
On entry: ξ, the forecast horizon.
Constraint: NT>0.
3:   IP – INTEGERInput
On entry: the number of coefficients, βi, for i=1,2,…,p.
Constraints:
  • max IP,IQ≤20;
  • IP≥0.
4:   IQ – INTEGERInput
On entry: the number of coefficients, αi, for i=1,2,…,q.
Constraints:
  • max IP,IQ≤20;
  • IQ≥1.
5:   THETA IQ+IP+1 – REAL (KIND=nag_wp) arrayInput
On entry: the first element must contain the coefficient αo and the next IQ elements must contain the coefficients αi, for i=1,2,…,q. The remaining IP elements must contain the coefficients βj, for j=1,2,…,p.
6:   GAMMA – REAL (KIND=nag_wp)Input
On entry: the asymmetry parameter γ for the GARCH p,q sequence.
7:   FHT NT – REAL (KIND=nag_wp) arrayOutput
On exit: the forecast values of the conditional variance, ht, for t=T+1,…,T+ξ.
8:   HT NUM – REAL (KIND=nag_wp) arrayInput
On entry: the sequence of past conditional variances for the GARCH p,q process, ht, for t=1,2,…,T.
9:   ET NUM – REAL (KIND=nag_wp) arrayInput
On entry: the sequence of past residuals for the GARCH p,q process, εt, for t=1,2,…,T.
10:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | NUM<max IP,IQ,
or | IQ<1,
or | IP<0,
or | max IP,IQ>20,
or | NT≤0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable

8 Parallelism and Performance

G13FFF is not threaded in any implementation.

9 Further Comments

None.

10 Example

See Section 10 in G13FEF.
G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13FGF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13FGF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13FGF estimates the parameters of a univariate regression-exponential GARCH p,q process (see Engle and Ng (1993)).

2 Specification

SUBROUTINE G13FGF ( DIST, YT, X, LDX, NUM, IP, IQ, NREG, MN, NPAR, THETA, SE, SC, COVR, LDCOVR, HP, ET, HT, LGF, COPTS, MAXIT, TOL, WORK, LWORK, IFAIL)
INTEGER | LDX, NUM, IP, IQ, NREG, MN, NPAR, LDCOVR, MAXIT, LWORK, IFAIL
REAL (KIND=nag_wp) | YT(NUM), X(LDX,*), THETA(NPAR), SE(NPAR), SC(NPAR), COVR(LDCOVR,NPAR), HP, ET(NUM), HT(NUM), LGF, TOL, WORK(LWORK)
LOGICAL | COPTS
CHARACTER(1) | DIST

3 Description

A univariate regression-exponential GARCH p,q process, with q coefficients αi, for i=1,2,…,q, q coefficients ϕi, for i=1,2,…,q, p coefficients, βi, for i=1,2,…,p, and k linear regression coefficients bi, for i=1,2,…,k, can be represented by:
yt = bo + xtT b + εt ln ht = α 0+ ∑ i=1 q αi z t-i + ∑ i=1 q ϕi z t-i - E z t-i + ∑ i=1 p βi ln h t-i ,   t=1,2,…,T (1)
where zt= εt ht , E z t-i denotes the expected value of z t-i and εt∣ψ t-1=N 0,ht or εt∣ψ t-1=St df,ht. Here St is a standardized Student's t-distribution with df degrees of freedom and variance ht, T is the number of terms in the sequence, yt denotes the endogenous variables, xt the exogenous variables, bo the regression mean, b the regression coefficients, εt the residuals, ht the conditional variance, df the number of degrees of freedom of the Student's t-distribution, and ψt the set of all information up to time t.
G13FGF provides an estimate θ^, for the vector θ = bo,bT,ωT where bT = b 1,…,bk , ωT = α 0,α 1,…,αq,ϕ 1,…,ϕq,β 1,…,βp,γ when DIST='N', and ωT = α 0,α 1,…,αq,ϕ 1,…,ϕq,β 1,…,βp,γ,df when DIST='T'.
MN, NREG can be used to simplify the GARCH p,q expression in (1) as follows:
No Regression and No Mean
  • yt=εt,
  • MN=0,
  • NREG=0 and
  • θ is a 2×q+p+1 vector when DIST='N', and a 2×q+p+2 vector, when DIST='T'.
No Regression
  • yt=bo+εt,
  • MN=1,
  • NREG=0 and
  • θ is a 2×q+p+2 vector when DIST='N' and a 2×q+p+3 vector, when DIST='T'.
Note: if the yt=μ+εt, where μ is known (not to be estimated by G13FGF) then (1) can be written as ytμ=εt, where ytμ=yt-μ. This corresponds to the case No Regression and No Mean, with yt replaced by yt-μ.
No Mean
  • yt = xtT b + εt ,
  • MN=0,
  • NREG=k and
  • θ is a 2×q+p+1+k vector when DIST='N' and a 2×q+p+2+k vector, when DIST='T'.

4 References

Bollerslev T (1986) Generalised autoregressive conditional heteroskedasticity Journal of Econometrics 31 307–327
Engle R (1982) Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation Econometrica 50 987–1008
Engle R and Ng V (1993) Measuring and testing the impact of news on volatility Journal of Finance 48 1749–1777
Glosten L, Jagannathan R and Runkle D (1993) Relationship between the expected value and the volatility of nominal excess return on stocks Journal of Finance 48 1779–1801
Hamilton J (1994) Time Series Analysis Princeton University Press

5 Arguments

1:   DIST – CHARACTER(1)Input
On entry: the type of distribution to use for et.
DIST='N'
A Normal distribution is used.
DIST='T'
A Student's t-distribution is used.
Constraint: DIST='N' or 'T'.
2:   YT NUM – REAL (KIND=nag_wp) arrayInput
On entry: the sequence of observations, yt, for t=1,2,…,T.
3:   X LDX* – REAL (KIND=nag_wp) arrayInput
Note: the second dimension of the array X must be at least NREG.
On entry: row t of X must contain the time dependent exogenous vector xt , where xtT = xt 1,…,xtk , for t=1,2,…,T.
4:   LDX – INTEGERInput
On entry: the first dimension of the array X as declared in the (sub)program from which G13FGF is called.
Constraint: LDX≥NUM.
5:   NUM – INTEGERInput
On entry: T, the number of terms in the sequence.
Constraints:
  • NUM≥max IP,IQ;
  • NUM≥NREG+MN.
6:   IP – INTEGERInput
On entry: the number of coefficients, βi, for i=1,2,…,p.
Constraint: IP≥0 (see also NPAR).
7:   IQ – INTEGERInput
On entry: the number of coefficients, αi, for i=1,2,…,q.
Constraint: IQ≥1 (see also NPAR).
8:   NREG – INTEGERInput
On entry: k, the number of regression coefficients.
Constraint: NREG≥0 (see also NPAR).
9:   MN – INTEGERInput
On entry: if MN=1, the mean term b 0 will be included in the model.
Constraint: MN=0 or 1.
10:   NPAR – INTEGERInput
On entry: the number of parameters to be included in the model. NPAR=1+2×IQ+IP+MN+NREG when DIST='N' and NPAR=2+2×IQ+IP+MN+NREG when DIST='T'.
Constraint: NPAR<20.
11:   THETA NPAR – REAL (KIND=nag_wp) arrayInput/Output
On entry: the initial parameter estimates for the vector θ.
The first element must contain the coefficient αo and the next IQ elements must contain the autoregressive coefficients αi, for i=1,2,…,q.
The next IQ elements contain the coefficients ϕi, for i=1,2,…,q.
The next IP elements must contain the moving average coefficients βi, for i=1,2,…,p.
If DIST='T', the next element must contain an estimate for df, the number of degrees of freedom of the Student's t-distribution.
If MN=1, the next element must contain the mean term bo.
If COPTS=.FALSE., the remaining NREG elements are taken as initial estimates of the linear regression coefficients bi, for i=1,2,…,k.
On exit: the estimated values θ^ for the vector θ.
The first element contains the coefficient αo and the next IQ elements contain the coefficients αi, for i=1,2,…,q.
The next IQ elements contain the coefficients ϕi, for i=1,2,…,q.
The next IP elements are the moving average coefficients βi, for i=1,2,…,p.
If DIST='T', the next element contains an estimate for df then the number of degrees of freedom of the Student's t-distribution.
If MN=1, the next element contains an estimate for the mean term bo.
The final NREG elements are the estimated linear regression coefficients bi, for i=1,2,…,k.
12:   SE NPAR – REAL (KIND=nag_wp) arrayOutput
On exit: the standard errors for θ^.
The first element contains the standard error for αo and the next IQ elements contain the standard errors for αi, for i=1,2,…,q. The next IQ elements contain the standard errors for ϕi, for i=1,2,…,q. The next IP elements are the standard errors for βj, for j=1,2,…,p.
If DIST='T', the next element contains the standard error for df, the number of degrees of freedom of the Student's t-distribution.
If MN=1, the next element contains the standard error for bo.
The final NREG elements are the standard errors for bj, for j=1,2,…,k.
13:   SC NPAR – REAL (KIND=nag_wp) arrayOutput
On exit: the scores for θ^.
The first element contains the scores for αo, the next IQ elements contain the scores for αi, for i=1,2,…,q, the next IQ elements contain the scores for ϕi, for i=1,2,…,q, the next IP elements are the scores for βj, for j=1,2,…,p.
If DIST='T', the next element contains the scores for df, the number of degrees of freedom of the Student's t-distribution.
If MN=1, the next element contains the score for bo.
The final NREG elements are the scores for bj, for j=1,2,…,k.
14:   COVR LDCOVRNPAR – REAL (KIND=nag_wp) arrayOutput
On exit: the covariance matrix of the parameter estimates θ^, that is the inverse of the Fisher Information Matrix.
15:   LDCOVR – INTEGERInput
On entry: the first dimension of the array COVR as declared in the (sub)program from which G13FGF is called.
Constraint: LDCOVR≥NPAR.
16:   HP – REAL (KIND=nag_wp)Input/Output
On entry: if COPTS=.FALSE. then HP is the value to be used for the pre-observed conditional variance, otherwise HP is not referenced.
On exit: if COPTS=.TRUE. then HP is the estimated value of the pre-observed conditional variance.
17:   ET NUM – REAL (KIND=nag_wp) arrayOutput
On exit: the estimated residuals, εt, for t=1,2,…,T.
18:   HT NUM – REAL (KIND=nag_wp) arrayOutput
On exit: the estimated conditional variances, ht, for t=1,2,…,T.
19:   LGF – REAL (KIND=nag_wp)Output
On exit: the value of the log-likelihood function at θ^.
20:   COPTS – LOGICALInput
On entry: if COPTS=.TRUE., the routine provides initial parameter estimates of the regression terms, otherwise these are provided by you.
21:   MAXIT – INTEGERInput
On entry: the maximum number of iterations to be used by the optimization routine when estimating the GARCH p,q parameters.
Constraint: MAXIT>0.
22:   TOL – REAL (KIND=nag_wp)Input
On entry: the tolerance to be used by the optimization routine when estimating the GARCH p,q parameters.
23:   WORK LWORK – REAL (KIND=nag_wp) arrayWorkspace
24:   LWORK – INTEGERInput
On entry: the dimension of the array WORK as declared in the (sub)program from which G13FGF is called.
Constraint: LWORK≥NREG+3×NUM+3.
25:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if IFAIL≠0 on exit, the recommended value is -1. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Note: G13FGF may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the routine:
IFAIL=1
On entry, | NREG<0,
or | MN>1,
or | MN<0,
or | IQ<1,
or | IP<0,
or | NPAR≥20,
or | NPAR has an invalid value,
or | LDCOVR<NPAR,
or | LDX<NUM,
or | DIST≠'N',
or | DIST≠'T',
or | MAXIT≤0,
or | NUM<max IP,IQ,
or | NUM<NREG+MN.
IFAIL=2
On entry, LWORK<NREG+3×NUM+3.
IFAIL=3
The matrix X is not full rank.
IFAIL=4
The information matrix is not positive definite.
IFAIL=5
The maximum number of iterations has been reached.
IFAIL=6
The log-likelihood cannot be optimized any further.
IFAIL=7
No feasible model parameters could be found.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

G13FGF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13FGF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

None.

10 Example

This example fits a GARCH 1,2 model with Student's t-distributed residuals to some simulated data.
The process parameter estimates, θ^, are obtained using G13FGF, and a four step ahead volatility estimate is computed using G13FHF.
The data was simulated using G05PGF.

10.1 Program Text

Program Text (g13fgfe.f90)

10.2 Program Data

Program Data (g13fgfe.d)

10.3 Program Results

Program Results (g13fgfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13FHF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13FHF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

G13FHF forecasts the conditional variances, ht,t=T+1,…,T+ξ from an exponential GARCH p,q sequence, where ξ is the forecast horizon and T is the current time (see Engle and Ng (1993)).

2 Specification

SUBROUTINE G13FHF ( NUM, NT, IP, IQ, THETA, FHT, HT, ET, IFAIL)
INTEGER | NUM, NT, IP, IQ, IFAIL
REAL (KIND=nag_wp) | THETA(2*IQ+IP+1), FHT(NT), HT(NUM), ET(NUM)

3 Description

Assume the GARCH p,q process represented by:
ln ht=α 0+∑i=1 q αiz t-i+∑j=1 q ϕi z t-j-E z t-i+∑j=1 p βi ln h t-j,  t=1,2,…,T.
where εt∣ψ t-1=N 0,ht or εt∣ψ t-1=St df,ht, and zt= εt ht , E z t-i denotes the expected value of z t-i, has been modelled by G13FGF, and the estimated conditional variances and residuals are contained in the arrays HT and ET respectively.
G13FHF will then use the last max p,q elements of the arrays HT and ET to estimate the conditional variance forecasts, ht∣ψT, where t=T+1,…,T+ξ and ξ is the forecast horizon.

4 References

Bollerslev T (1986) Generalised autoregressive conditional heteroskedasticity Journal of Econometrics 31 307–327
Engle R (1982) Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation Econometrica 50 987–1008
Engle R and Ng V (1993) Measuring and testing the impact of news on volatility Journal of Finance 48 1749–1777
Glosten L, Jagannathan R and Runkle D (1993) Relationship between the expected value and the volatility of nominal excess return on stocks Journal of Finance 48 1779–1801
Hamilton J (1994) Time Series Analysis Princeton University Press

5 Arguments

1:   NUM – INTEGERInput
On entry: the number of terms in the arrays HT and ET from the modelled sequence.
Constraint: max IP,IQ≤NUM.
2:   NT – INTEGERInput
On entry: ξ, the forecast horizon.
Constraint: NT>0.
3:   IP – INTEGERInput
On entry: the number of coefficients, βi, for i=1,2,…,p.
Constraints:
  • max IP,IQ≤20;
  • IP≥0.
4:   IQ – INTEGERInput
On entry: the number of coefficients, αi, for i=1,2,…,q.
Constraints:
  • max IP,IQ≤20;
  • IQ≥1.
5:   THETA 2×IQ+IP+1 – REAL (KIND=nag_wp) arrayInput
On entry: the initial parameter estimates for the vector θ. The first element must contain the coefficient αo and the next IQ elements must contain the autoregressive coefficients αi, for i=1,2,…,q. The next IQ elements must contain the coefficients ϕi, for i=1,2,…,q. The next IP elements must contain the moving average coefficients βj, for j=1,2,…,p.
6:   FHT NT – REAL (KIND=nag_wp) arrayOutput
On exit: the forecast values of the conditional variance, ht, for t=T+1,…,T+ξ.
7:   HT NUM – REAL (KIND=nag_wp) arrayInput
On entry: the sequence of past conditional variances for the GARCH p,q process, ht, for t=1,2,…,T.
8:   ET NUM – REAL (KIND=nag_wp) arrayInput
On entry: the sequence of past residuals for the GARCH p,q process, εt, for t=1,2,…,T.
9:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | NUM<max IP,IQ,
or | IQ<1,
or | IP<0,
or | max IP,IQ>20,
or | NT≤0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

G13FHF is not threaded in any implementation.

9 Further Comments

None.

10 Example

See Section 10 in G13FGF.
G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13 Chapter Introduction : NAG Library, Mark 26

G13 Chapter Contents

NAG Library Chapter Introduction

G13 – Time Series Analysis

▸▿ Contents

1 Scope of the Chapter
▸▿ 2 Background to the Problems
▸▿ 2.1 Univariate Analysis
2.1.1 Transformations
2.1.2 Differencing operations
2.1.3 Sample autocorrelations
2.1.4 Partial autocorrelations
2.1.5 Finite lag predictor coefficients and error variances
2.1.6 ARIMA models
2.1.7 ARIMA model estimation
2.1.8 ARIMA model forecasting
2.1.9 Exponential smoothing
2.1.10 Change point analysis
▸▿ 2.2 Univariate Spectral Analysis
2.2.1 The sample spectrum
2.2.2 Spectral smoothing by lag window
2.2.3 Direct spectral smoothing
▸▿ 2.3 Linear Lagged Relationships Between Time Series
2.3.1 Transfer function models
2.3.2 Cross-correlations
2.3.3 Prewhitening or filtering by an ARIMA model
2.3.4 Multi-input model estimation
2.3.5 Multi-input model forecasting
2.3.6 Transfer function model filtering
▸▿ 2.4 Multivariate Time Series
2.4.1 Differencing and transforming a multivariate time series
2.4.2 Model identification for a multivariate time series
2.4.3 VARMA model estimation
2.4.4 VARMA model forecasting
▸▿ 2.5 Cross-spectral Analysis
2.5.1 The sample cross-spectrum
2.5.2 The amplitude and phase spectrum
2.5.3 The coherency spectrum
2.5.4 The gain and noise spectrum
2.5.5 Cross-spectrum smoothing by lag window
2.5.6 Direct smoothing of the cross-spectrum
▸▿ 2.6 Kalman Filters
▸▿ 2.6.1 Linear State Space Models
2.6.1.1 Computational methods
2.6.1.2 Model fitting and forecasting
2.6.1.3 Kalman filter and time series models
2.6.2 Nonlinear State Space Models
▸▿ 2.7 GARCH Models
2.7.1 ARCH models and their generalizations
2.7.2 Fitting GARCH models
2.8 Inhomogeneous Time Series
▸▿ 3 Recommendations on Choice and Use of Available Routines
▸▿ 3.1 Univariate Analysis
3.1.1 ARMA-type Models
3.1.2 Exponential smoothing
3.1.3 Change point analysis
3.2 Univariate Spectral Analysis
3.3 Linear Lagged Relationships Between Time Series
3.4 Multivariate Time Series
3.5 Cross-spectral Analysis
▸▿ 3.6 Kalman Filtering
3.6.1 Linear state space models
3.6.2 Nonlinear state space models
3.7 GARCH Models
3.8 Inhomogeneous Time Series
3.9 Time Series Simulation
4 Functionality Index
5 Auxiliary Routines Associated with Library Routine Arguments
6 Routines Withdrawn or Scheduled for Withdrawal
7 References

1 Scope of the Chapter

This chapter provides facilities for investigating and modelling the statistical structure of series of observations collected at points in time. The models may then be used to forecast the series.
The chapter covers the following models and approaches.
1. | Univariate time series analysis, including autocorrelation functions and autoregressive moving average (ARMA) models.
2. | Univariate spectral analysis.
3. | Transfer function (multi-input) modelling, in which one time series is dependent on other time series.
4. | Bivariate spectral methods including coherency, gain and input response functions.
5. | Vector ARMA models for multivariate time series.
6. | Kalman filter models (linear and nonlinear).
7. | GARCH models for volatility.
8. | Inhomogeneous Time Series.

2 Background to the Problems

2.1 Univariate Analysis

Let the given time series be x 1,x 2,…,xn, where n is its length. The structure which is intended to be investigated, and which may be most evident to the eye in a graph of the series, can be broadly described as:
(a) | trends, linear or possibly higher-order polynomial;
(b) | seasonal patterns, associated with fixed integer seasonal periods. The presence of such seasonality and the period will normally be known a priori. The pattern may be fixed, or slowly varying from one season to another;
(c) | cycles or waves of stable amplitude and period p (from peak to peak). The period is not necessarily integer, the corresponding absolute frequency (cycles/time unit) being f=1/p and angular frequency ω=2 πf. The cycle may be of pure sinusoidal form like sin ωt, or the presence of higher harmonic terms may be indicated, e.g., by asymmetry in the wave form;
(d) | quasi-cycles, i.e., waves of fluctuating period and amplitude; and
(e) | irregular statistical fluctuations and swings about the overall mean or trend.
Trends, seasonal patterns, and cycles might be regarded as deterministic components following fixed mathematical equations, and the quasi-cycles and other statistical fluctuations as stochastic and describable by short-term correlation structure. For a finite dataset it is not always easy to discriminate between these two types, and a common description using the class of autoregressive integrated moving-average (ARIMA) models is now widely used. The form of these models is that of difference equations (or recurrence relations) relating present and past values of the series. You are referred to Box and Jenkins (1976) for a thorough account of these models and how to use them. We follow their notation and outline the recommended steps in ARIMA model building for which routines are available.

2.1.1 Transformations

If the variance of the observations in the series is not constant across the range of observations it may be useful to apply a variance-stabilizing transformation to the series. A common situation is for the variance to increase with the magnitude of the observations and in this case typical transformations used are the log or square root transformation. A range-mean plot or standard deviation-mean plot provides a quick and easy way of detecting non-constant variance and of choosing, if required, a suitable transformation. These are plots of either the range or standard deviation of successive groups of observations against their means.

2.1.2 Differencing operations

These may be used to simplify the structure of a time series.
First-order differencing, i.e., forming the new series
∇xt=xt-x t-1
will remove a linear trend. First-order seasonal differencing
∇sxt=xt-x t-s
eliminates a fixed seasonal pattern.
These operations reflect the fact that it is often appropriate to model a time series in terms of changes from one value to another. Differencing is also therefore appropriate when the series has something of the nature of a random walk, which is by definition the accumulation of independent changes.
Differencing may be applied repeatedly to a series, giving
wt=∇d∇sD xt
where d and D are the orders of differencing. The derived series wt will be shorter, of length N=n-d-s×D, and extend for t=1+d+s×D,…,n.

2.1.3 Sample autocorrelations

Given that a series has (possibly as a result of simplifying by differencing operations) a homogeneous appearance throughout its length, fluctuating with approximately constant variance about an overall mean level, it is appropriate to assume that its statistical properties are stationary. For most purposes the correlations ρk between terms xt,x t+k or wt,w t+k separated by lag k give an adequate description of the statistical structure and are estimated by the sample autocorrelation function (ACF) rk, for k=1,2,….
As described by Box and Jenkins (1976), these may be used to indicate which particular ARIMA model may be appropriate.

2.1.4 Partial autocorrelations

The information in the autocorrelations, ρk, may be presented in a different light by deriving from them the coefficients of the partial autocorrelation function (PACF) ϕ k,k, for k=1,2,…. ϕ k,k which measures the correlation between xt and x t+k conditional upon the intermediate values x t+1,x t+2,…,x t+k-1. The corresponding sample values ϕ^k,k give further assistance in the selection of ARIMA models.
Both autocorrelation function (ACF) and PACF may be rapidly computed, particularly in comparison with the time taken to estimate ARIMA models.

2.1.5 Finite lag predictor coefficients and error variances

The partial autocorrelation coefficient ϕ k,k is determined as the final parameter in the minimum variance predictor of xt in terms of x t-1,x t-2,…,x t-k,
xt=ϕ k,1x t-1+ϕ k,2x t-2+⋯+ϕ k,kx t-k+e k,t
where e k,t is the prediction error, and the first subscript k of ϕ k,i and e k,t emphasizes the fact that the parameters will alter as k increases. Moderately good estimates ϕ^k,i of ϕ k,i are obtained from the sample autocorrelation function (ACF), and after calculating the partial autocorrelation function (PACF) up to lag L, the successive values v 1,v 2,…,vL of the prediction error variance estimates, vk=var e k,t, are available, together with the final values of the coefficients ϕ^k,1,ϕ^k,2,…,ϕ^k,L. If xt has nonzero mean, x-, it is adequate to use xt-x- in place of xt in the prediction equation.
Although Box and Jenkins (1976) do not place great emphasis on these prediction coefficients, their use is advocated for example by Akaike (1971), who recommends selecting an optimal order of the predictor as the lag for which the final prediction error (FPE) criterion 1+k/n 1-k/n-1 vk is a minimum.

2.1.6 ARIMA models

The correlation structure in stationary time series may often be represented by a model with a small number of parameters belonging to the autoregressive moving-average (ARMA) class. If the stationary series wt has been derived by differencing from the original series xt, then xt is said to follow an ARIMA model. Taking wt=∇d xt, the (non-seasonal) ARIMA p,d,q model with p autoregressive parameters ϕ 1,ϕ 2,…,ϕp and q moving-average parameters θ 1,θ 2,…,θq, represents the structure of wt by the equation
wt=ϕ 1w t-1+⋯+ϕpw t-p+at-θ 1a t-1-⋯-θqa t-q, (1)
where at is an uncorrelated series (white noise) with mean 0 and constant variance σa 2. If wt has a nonzero mean c, then this is allowed for by replacing wt,w t-1,… by wt-c,w t-1-c,… in the model. Although c is often estimated by the sample mean of wt this is not always optimal.
A series generated by this model will only be stationary provided restrictions are placed on ϕ 1,ϕ 2,…,ϕp to avoid unstable growth of wt. These are called stationarity constraints. The series at may also be usefully interpreted as the linear innovations in xt (and in wt), i.e., the error if xt were to be predicted using the information in all past values x t-1,x t-2,…, provided also that θ 1,θ 2,…,θq satisfy invertibility constraints. This allows the series at to be regenerated by rewriting the model equation as
at=wt-ϕ 1w t-1-⋯-ϕpw t-p+θ 1a t-1+⋯+θqa t-q. (2)
For a series with short-term correlation only, i.e., rk is not significant beyond some low lag q (see Box and Jenkins (1976) for the statistical test), then the pure moving-average model MA q is appropriate, with no autoregressive parameters, i.e., p=0.
Autoregressive parameters are appropriate when the autocorrelation function (ACF) pattern decays geometrically, or with a damped sinusoidal pattern which is associated with quasi-periodic behaviour in the series. If the sample partial autocorrelation function (PACF) ϕ^k,k is significant only up to some low lag p, then a pure autoregressive model AR p is appropriate, with q=0. Otherwise moving-average terms will need to be introduced, as well as autoregressive terms.
The seasonal ARIMA p,d,q,P,D,Q,s model allows for correlation at lags which are multiples of the seasonal period s. Taking wt=∇d∇sD xt, the series is represented in a two-stage manner via an intermediate series et:
wt=Φ 1w t-s+⋯+ΦPw t-s×P+et-Θ 1e t-s-⋯-ΘQe t-s×Q (3)
et=ϕ 1e t-1+⋯+ϕpe t-p+at-θ 1a t-1-⋯-θqa t-q (4)
where Φi, Θi are the seasonal parameters and P and Q are the corresponding orders. Again, wt may be replaced by wt-c.

2.1.7 ARIMA model estimation

In theory, the parameters of an ARIMA model are determined by a sufficient number of autocorrelations ρ 1,ρ 2,…. Using the sample values r 1,r 2,… in their place it is usually (but not always) possible to solve for the corresponding ARIMA parameters.
These are rapidly computed but are not fully efficient estimates, particularly if moving-average parameters are present. They do provide useful preliminary values for an efficient but relatively slow iterative method of estimation. This is based on the least squares principle by which parameters are chosen to minimize the sum of squares of the innovations at, which are regenerated from the data using (2), or the reverse of (3) and (4) in the case of seasonal models.
Lack of knowledge of terms on the right-hand side of (2), when t=1,2,…,max p,q, is overcome by introducing q unknown series values w 0,w 1,…,w q-1 which are estimated as nuisance parameters, and using correction for transient errors due to the autoregressive terms. If the data w 1,w 2,…,wN=w is viewed as a single sample from a multivariate Normal density whose covariance matrix V is a function of the ARIMA model parameters, then the exact likelihood of the parameters is
-12 log V-12 wTV-1 w.
The least squares criterion as outlined above is equivalent to using the quadratic form
QF=wTV-1 w
as an objective function to be minimized. Neglecting the term -12log V yields estimates which differ very little from the exact likelihood except in small samples, or in seasonal models with a small number of whole seasons contained in the data. In these cases bias in moving-average parameters may cause them to stick at the boundary of their constraint region, resulting in failure of the estimation method.
Approximate standard errors of the parameter estimates and the correlations between them are available after estimation.
The model residuals, a^t, are the innovations resulting from the estimation and are usually examined for the presence of autocorrelation as a check on the adequacy of the model.

2.1.8 ARIMA model forecasting

An ARIMA model is particularly suited to extrapolation of a time series. The model equations are simply used for t=n+1,n+2,… replacing the unknown future values of at by zero. This produces future values of wt, and if differencing has been used this process is reversed (the so-called integration part of ARIMA models) to construct future values of xt.
Forecast error limits are easily deduced.
This process requires knowledge only of the model orders and parameters together with a limited set of the terms a t-i,e t-i,w t-i,x t-i which appear on the right-hand side of the models (3) and (4) (and the differencing equations) when t=n. It does not require knowledge of the whole series.
We call this the state set. It is conveniently constituted after model estimation. Moreover, if new observations x n+1,x n+2,… come to hand, then the model equations can easily be used to update the state set before constructing forecasts from the end of the new observations. This is particularly useful when forecasts are constructed on a regular basis. The new innovations a n+1,a n+2,… may be compared with the residual standard deviation, σa, of the model used for forecasting, as a check that the model is continuing to forecast adequately.

2.1.9 Exponential smoothing

Exponential smoothing is a relatively simple method of short term forecasting for a time series. A variety of different smoothing methods are possible, including; single exponential, Brown's double exponential, linear Holt (also called double exponential smoothing in some references), additive Holt–Winters and multiplicative Holt–Winters. The choice of smoothing method used depends on the characteristics of the time series. If the mean of the series is only slowly changing then single exponential smoothing may be suitable. If there is a trend in the time series, which itself may be slowly changing, then linear Holt smoothing may be suitable. If there is a seasonal component to the time series, e.g., daily or monthly data, then one of the two Holt–Winters methods may be suitable.
For a time series yt, for t=1,2,…,n, the five smoothing functions are defined by the following:
  • Single Exponential Smoothing
    mt = α yt + 1-α m t-1 y^t+f =mt var y^t+f = var εt 1+ f-1 α 2
  • Brown Double Exponential Smoothing
    mt = α yt + 1-α m t-1 rt = α mt - m t-1 + 1-α r t-1 y^ t+f = mt + f-1 + 1 / α rt var y^ t+f = var εt 1+ ∑ i=1 f-1 2 α+ i-1 α 2 2
  • Linear Holt Smoothing
    mt = α yt + 1-α m t-1 + ϕ r t-1 rt = γ mt - m t-1 + 1-γ ϕ r t-1 y^ t+f = mt + ∑ i=1 f ϕi rt var y^ t+f = var εt 1+ ∑ i=1 f-1 α + α γ ϕ ϕi-1 ϕ-1 2
  • Additive Holt–Winters Smoothing
    mt = α yt - s t-p + 1-α m t-1 +ϕ r t-1 rt = γ mt - m t-1 + 1-γ ϕ r t-1 st = β yt - mt + 1-β s t-p y^ t+f = mt + ∑ i=1 f ϕi rt + s t-p var y^ t+f = var εt 1+ ∑ i=1 f-1 ψi 2 ψi = 0 if ​i≥f α + αγϕ ϕ i -1 ϕ-1 if ​ i mod p≠0 α + α γ ϕ ϕi -1 ϕ-1 +β 1-α otherwise
  • Multiplicative Holt–Winters Smoothing
    mt = α yt / s t-p + 1-α m t-1 +ϕ r t-1 rt = γ mt - m t-1 + 1-γ ϕ r t-1 st = β yt / mt + 1-β s t-p y^ t+f = mt + ∑ i=1 f ϕi rt × s t-p var y^ t+f = var εt ∑ i=0 ∞ ∑ j=0 p-1 ψ j+ip s t+f s t+f-j 2
    and ψ is defined as in the additive Holt–Winters smoothing,
where mt is the mean, rt is the trend and st is the seasonal component at time t with p being the seasonal order. The f-step ahead forecasts are given by y^t+f and their variances by var y^ t+f . The term var εt is estimated as the mean deviation.
The parameters, α, β and γ control the amount of smoothing. The nearer these parameters are to one, the greater the emphasis on the current data point. Generally these parameters take values in the range 0.1 to 0.3. The linear Holt and two Holt–Winters smoothers include an additional parameter, ϕ, which acts as a trend dampener. For 0.0<ϕ<1.0 the trend is dampened and for ϕ>1.0 the forecast function has an exponential trend, ϕ=0.0 removes the trend term from the forecast function and ϕ=1.0 does not dampen the trend.
For all methods, values for α, β, γ and ψ can be chosen by trying different values and then visually comparing the results by plotting the fitted values along side the original data. Alternatively, for single exponential smoothing a suitable value for α can be obtained by fitting an ARIMA 0,1,1 model. For Brown's double exponential smoothing and linear Holt smoothing with no dampening, (i.e., ϕ=1.0), suitable values for α and, in the case of linear Holt smoothing, γ can be obtained by fitting an ARIMA 0,2,2 model. Similarly, the linear Holt method, with ϕ≠1.0, can be expressed as an ARIMA 1,2,2 model and the additive Holt–Winters, with no dampening, (ϕ=1.0), can be expressed as a seasonal ARIMA model with order p of the form ARIMA 0,1,p+10,1,0. There is no similar procedure for obtaining parameter values for the multiplicative Holt–Winters method, or the additive Holt–Winters method with ϕ≠1.0. In these cases parameters could be selected by minimizing a measure of fit using nonlinear optimization.

2.1.10 Change point analysis

Given a time series y 1:n=yj:j=1,2,…,n, a change point τ is a place or time point such that segment of the series up to τ, y 1:τ, follows one distribution and the segment after τ, y τ+1:n, follows a different distribution. This idea can be extended to m change points, in which case τ=τi:i=1,2,…,m becomes a vector of ordered (strictly monotonic increasing) change points with 1≤τi≤n and τm=n. The ith segment therefore consists of y τ i-1+1:τi where, for ease of notation, we define τ 0=0. A change point problem is therefore twofold: estimating m the number of change points (and hence the number of segments) and estimating τ the location of those change points.
Given a cost function, C y τ i-1+1:τi one formulation of the change point problem can be expressed as the solution to:
minimize m,τ ∑ i=1 m C y τ i-1+1:τi + β (5)
where β is a penalty term used to control the number of change points. Two methods of solving equation (5) are available: the PELT algorithm and binary segmentation. The Pruned Exact Linear Time (PELT) algorithm of Killick et al. (2012) is a tree based method which is guaranteed to return the optimal solution to (5) as long as there exists a constant K such that
C y u+1 : v + C y v+1 : w + K ≤ C y u+1 : w (6)
for all u<v<w. Unlike PELT, binary segmentation is an iterative method that only results in an approximate solution to (5). A description of the binary segmentation algorithm can be found in Section 3 in G13NDF and G13NEF.

2.2 Univariate Spectral Analysis

In describing a time series using spectral analysis the fundamental components are taken to be sinusoidal waves of the form R cos ωt+ϕ, which for a given angular frequency ω, 0≤ω≤π, is specified by its amplitude R>0 and phase ϕ, 0≤ϕ<2 π. Thus in a time series of n observations it is not possible to distinguish more than n/2 independent sinusoidal components. The frequency range 0≤ω≤π is limited to the shortest wavelength of two sampling units because any wave of higher frequency is indistinguishable upon sampling (or is aliased with) a wave within this range. Spectral analysis follows the idea that for a series made up of a finite number of sine waves the amplitude of any component at frequency ω is given to order 1/n by
R 2= 1 n 2 ∑ t=1 n xt e iωt 2 .

2.2.1 The sample spectrum

For a series x 1,x 2,…,xn this is defined as
f* ω= 1 2 nπ ∑ t=1 n xt e iωt 2 ,
the scaling factor now being chosen in order that
2∫0 π f*ω dω=σx 2,
i.e., the spectrum indicates how the sample variance (σx 2) of the series is distributed over components in the frequency range 0≤ω≤π.
It may be demonstrated that f*ω is equivalently defined in terms of the sample ACF rk of the series as
f*ω=1 2 π c 0+2∑k=1 n-1 ck cos⁡k ω ,
where ck=σx 2 rk are the sample autocovariance coefficients.
If the series xt does contain a deterministic sinusoidal component of amplitude R, this will be revealed in the sample spectrum as a sharp peak of approximate width π/n and height n/2 π R 2. This is called the discrete part of the spectrum, the variance R 2 associated with this component being in effect concentrated at a single frequency.
If the series xt has no deterministic components, i.e., is purely stochastic being stationary with autocorrelation function (ACF) rk, then with increasing sample size the expected value of f*ω converges to the theoretical spectrum – the continuous part
f ω=1 2 π γ 0+2∑k=1∞γk cos ωk ,
where γk are the theoretical autocovariances.
The sample spectrum does not however converge to this value but at each frequency point fluctuates about the theoretical spectrum with an exponential distribution, being independent at frequencies separated by an interval of 2 π/n or more. Various devices are therefore employed to smooth the sample spectrum and reduce its variability. Much of the strength of spectral analysis derives from the fact that the error limits are multiplicative so that features may still show up as significant in a part of the spectrum which has a generally low level, whereas they are completely masked by other components in the original series. The spectrum can help to distinguish deterministic cyclical components from the stochastic quasi-cycle components which produce a broader peak in the spectrum. (The deterministic components can be removed by regression and the remaining part represented by an ARIMA model.)
A large discrete component in a spectrum can distort the continuous part over a large frequency range surrounding the corresponding peak. This may be alleviated at the cost of slightly broadening the peak by tapering a portion of the data at each end of the series with weights which decay smoothly to zero. It is usual to correct for the mean of the series and for any linear trend by simple regression, since they would similarly distort the spectrum.

2.2.2 Spectral smoothing by lag window

The estimate is calculated directly from the sample autocovariances ck as
f ω=1 2 π c 0+2∑k=1 M-1 wkck cos⁡k ω ,
the smoothing being induced by the lag window weights wk which extend up to a truncation lag M which is generally much less than n. The smaller the value of M, the greater the degree of smoothing, the spectrum estimates being independent only at a wider frequency separation indicated by the bandwidth b which is proportional to 1/M. It is wise, however, to calculate the spectrum at intervals appreciably less than this. Although greater smoothing narrows the error limits, it can also distort the spectrum, particularly by flattening peaks and filling in troughs.

2.2.3 Direct spectral smoothing

The unsmoothed sample spectrum is calculated for a fine division of frequencies, then averaged over intervals centred on each frequency point for which the smoothed spectrum is required. This is usually at a coarser frequency division. The bandwidth corresponds to the width of the averaging interval.

2.3 Linear Lagged Relationships Between Time Series

We now consider the context in which one time series, called the dependent or output series, y 1,y 2,…,yn, is believed to depend on one or more explanatory or input series, e.g., x 1,x 2,…,xn. This dependency may follow a simple linear regression, e.g.,
yt=v xt+nt
or more generally may involve lagged values of the input
yt=v 0xt+v 1x t- 1+v 2x t- 2+⋯+nt.
The sequence v 0,v 1,v 2,… is called the impulse response function (IRF) of the relationship. The term nt represents that part of yt which cannot be explained by the input, and it is assumed to follow a univariate ARIMA model. We call nt the (output) noise component of yt, and it includes any constant term in the relationship. It is assumed that the input series, xt, and the noise component, nt, are independent.
The part of yt which is explained by the input is called the input component zt:
zt=v 0xt+v 1x t-1+v 2x t-2+⋯
so yt=zt+nt.
The eventual aim is to model both these components of yt on the basis of observations of y 1,y 2,…,yn and x 1,x 2,…,xn. In applications to forecasting or control both components are important. In general there may be more than one input series, e.g., x 1,t and x 2,t, which are assumed to be independent and corresponding components z 1,t and z 2,t, so
yt=z 1,t+z 2,t+nt.

2.3.1 Transfer function models

In a similar manner to that in which the structure of a univariate series may be represented by a finite-parameter ARIMA model, the structure of an input component may be represented by a transfer function (TF) model with delay time b, p autoregressive-like parameters δ 1,δ 2,…,δp and q+1 moving-average-like parameters ω 0,ω 1,…,ωq:
zt=δ 1z t-1+δ 2z t-2+⋯+δpz t-p+ω 0x t-b-ω 1x t-b-1-⋯-ωqx t-b-q. (7)
If p>0 this represents an impulse response function (IRF) which is infinite in extent and decays with geometric and/or sinusoidal behaviour. The parameters δ 1,δ 2,…,δp are constrained to satisfy a stability condition identical to the stationarity condition of autoregressive models. There is no constraint on ω 0,ω 1,…,ωq.

2.3.2 Cross-correlations

An important tool for investigating how an input series xt affects an output series yt is the sample cross-correlation function (CCF) r xy k, for k=0,1,… between the series. If xt and yt are (jointly) stationary time series this is an estimator of the theoretical quantity
ρ xy k=corr xt,y t+k.
The sequence r yx k, for k=0,1,…, is distinct from r xy k, though it is possible to interpret
r yx k=r xy-k.
When the series yt and xt are believed to be related by a transfer function (TF) model, the CCF is determined by the impulse response function (IRF) v 0,v 1,v 2,… and the autocorrelation function (ACF) of the input xt.
In the particular case when xt is an uncorrelated series or white noise (and is uncorrelated with any other inputs):
ρ xy k∝vk
and the sample CCF can provide an estimate of vk:
v~k=sy/sx r xy k
where sy and sx are the sample standard deviations of yt and xt, respectively.
In theory the IRF coefficients vb,…,v b+p+q determine the parameters in the TF model, and using v~k to estimate v~k it is possible to solve for preliminary estimates of δ 1,δ 2,…,δp, ω 0,ω 1,…,ωq.

2.3.3 Prewhitening or filtering by an ARIMA model

In general an input series xt is not white noise, but may be represented by an ARIMA model with innovations or residuals at which are white noise. If precisely the same operations by which at is generated from xt are applied to the output yt to produce a series bt, then the transfer function relationship between yt and xt is preserved between bt and at. It is then possible to estimate
v~k=sb/sa r ab k.
The procedure of generating at from xt (and bt from yt) is called prewhitening or filtering by an ARIMA model. Although at is necessarily white noise, this is not generally true of bt.

2.3.4 Multi-input model estimation

The term multi-input model is used for the situation when one output series yt is related to one or more input series x j,t, as described in Section 2.3. If for a given input the relationship is a simple linear regression, it is called a simple input; otherwise it is a transfer function input. The error or noise term follows an ARIMA model.
Given that the orders of all the transfer function models and the ARIMA model of a multi-input model have been specified, the various parameters in those models may be (simultaneously) estimated.
The procedure used is closely related to the least squares principle applied to the innovations in the ARIMA noise model.
The innovations are derived for any proposed set of parameter values by calculating the response of each input to the transfer functions and then evaluating the noise nt as the difference between this response (combined for all the inputs) and the output. The innovations are derived from the noise using the ARIMA model in the same manner as for a univariate series, and as described in Section 2.1.6.
In estimating the parameters, consideration has to be given to the lagged terms in the various model equations which are associated with times prior to the observation period, and are therefore unknown. The subroutine descriptions provide the necessary detail as to how this problem is treated.
Also, as described in Section 2.1.7 the sum of squares criterion
S=∑at 2
is related to the quadratic form in the exact log-likelihood of the parameters:
-12 log V-12 wTV-1 w.
Here w is the vector of appropriately differenced noise terms, and
wTV-1 w=S/σa 2,
where σa 2 is the innovation variance parameter.
The least squares criterion is therefore identical to minimization of the quadratic form, but is not identical to exact likelihood. Because V may be expressed as M σa 2, where M is a function of the ARIMA model parameters, substitution of σa 2 by its maximum likelihood (ML) estimator yields a concentrated (or profile) likelihood which is a function of
M 1/N S.
N is the length of the differenced noise series w, and M=det⁡M.
Use of the above quantity, called the deviance, D, as an objective function is preferable to the use of S alone, on the grounds that it is equivalent to exact likelihood, and yields estimates with better properties. However, there is an appreciable computational penalty in calculating D, and in large samples it differs very little from S, except in the important case of seasonal ARIMA models where the number of whole seasons within the data length must also be large.
You are given the option of taking the objective function to be either S or D, or a third possibility, the marginal likelihood. This is similar to exact likelihood but can counteract bias in the ARIMA model due to the fitting of a large number of simple inputs.
Approximate standard errors of the parameter estimates and the correlations between them are available after estimation.
The model residuals a^t are the innovations resulting from the estimation, and they are usually examined for the presence of either autocorrelation or cross-correlation with the inputs. Absence of such correlation provides some confirmation of the adequacy of the model.

2.3.5 Multi-input model forecasting

A multi-input model may be used to forecast the output series provided future values (possibly forecasts) of the input series are supplied.
Construction of the forecasts requires knowledge only of the model orders and parameters, together with a limited set of the most recent variables which appear in the model equations. This is called the state set. It is conveniently constituted after model estimation. Moreover, if new observations y n+1,y n+2,… of the output series and x n+1,x n+2,… of (all) the independent input series become available, then the model equations can easily be used to update the state set before constructing forecasts from the end of the new observations. The new innovations a n+1,a n+2,… generated in this updating may be used to monitor the continuing adequacy of the model.

2.3.6 Transfer function model filtering

In many time series applications it is desired to calculate the response (or output) of a transfer function (TF) model for a given input series.
Smoothing, detrending, and seasonal adjustment are typical applications. You must specify the orders and parameters of a TF model for the purpose being considered. This may then be applied to the input series.
Again, problems may arise due to ignorance of the input series values prior to the observation period. The transient errors which can arise from this may be substantially reduced by using ‘backforecasts’ of these unknown observations.

2.4 Multivariate Time Series

Multi-input modelling represents one output time series in terms of one or more input series. Although there are circumstances in which it may be more appropriate to analyse a set of time series by modelling each one in turn as the output series with the remainder as inputs, there is a more symmetric approach in such a context. These models are known as vector autoregressive moving-average (VARMA) models.

2.4.1 Differencing and transforming a multivariate time series

As in the case of a univariate time series, it may be useful to simplify the series by differencing operations which may be used to remove linear or seasonal trends, thus ensuring that the resulting series to be used in the model estimation is stationary. It may also be necessary to apply transformations to the individual components of the multivariate series in order to stabilize the variance. Commonly used transformations are the log and square root transformations.

2.4.2 Model identification for a multivariate time series

Multivariate analogues of the autocorrelation and partial autocorrelation functions are available for analysing a set of k time series, x i,1,x i,2,…,x i,n, for i=1,2,…,k, thereby making it possible to obtain some understanding of a suitable VARMA model for the observed series.
It is assumed that the time series have been differenced if necessary, and that they are jointly stationary. The lagged correlations between all possible pairs of series, i.e.,
ρ ijl = corr x i , t , x j , t + l
are then taken to provide an adequate description of the statistical relationships between the series. These quantities are estimated by sample auto- and cross-correlations r ijl. For each l these may be viewed as elements of a (lagged) autocorrelation matrix.
Thus consider the vector process xt (with elements x it) and lagged autocovariance matrices Γl with elements of σiσjρ ijl where σi 2=var x i,t. Correspondingly, Γl is estimated by the matrix Cl with elements sisjr ijl where si 2 is the sample variance of x it.
For a series with short-term cross-correlation only, i.e., r ijl is not significant beyond some low lag q, then the pure vector MA q model, with no autoregressive parameters, i.e., p=0, is appropriate.
The correlation matrices provide a description of the joint statistical properties of the series. It is also possible to calculate matrix quantities which are closely analogous to the partial autocorrelations of univariate series (see Section 2.1.4). Wei (1990) discusses both the partial autoregression matrices proposed by Tiao and Box (1981) and partial lag correlation matrices.
In the univariate case the partial autocorrelation function (PACF) between xt and x t+l is the correlation coefficient between the two after removing the linear dependence on each of the intervening variables x t+1,x t+2,…,x t+l-1. This partial autocorrelation may also be obtained as the last regression coefficient associated with xt when regressing x t+l on its l lagged variables x t+l-1,x t+l-2,…,xt. Tiao and Box (1981) extended this method to the multivariate case to define the partial autoregression matrix. Heyse and Wei (1985) also extended the univariate definition of the PACF to derive the correlation matrix between the vectors xt and x t+l after removing the linear dependence on each of the intervening vectors x t+1,x t+2,…,x t+l-1, the partial lag correlation matrix.
Note that the partial lag correlation matrix is a correlation coefficient matrix since each of its elements is a properly normalized correlation coefficient. This is not true of the partial autoregression matrices (except in the univariate case for which the two types of matrix are the same). The partial lag correlation matrix at lag 1 also reduces to the regular correlation matrix at lag 1; this is not true of the partial autoregression matrices (again except in the univariate case).
Both the above share the same cut-off property for autoregressive processes; that is for an autoregressive process of order p, the terms of the matrix at lags p+1 and greater are zero. Thus if the sample partial cross-correlations are significant only up to some low lag p then a pure vector AR p model is appropriate with q=0. Otherwise moving-average terms will need to be introduced as well as autoregressive terms.
Under the hypothesis that xt is an autoregressive process of order l-1, n times the sum of the squared elements of the partial lag correlation matrix at lag l is asymptotically distributed as a χ 2 variable with k 2 degrees of freedom where k is the dimension of the multivariate time series. This provides a diagnostic aid for determining the order of an autoregressive model.
The partial autoregression matrices may be found by solving a multivariate version of the Yule–Walker equations to find the autoregression matrices, using the final regression matrix coefficient as the partial autoregression matrix at that particular lag.
The basis of these calculations is a multivariate autoregressive model:
xt=ϕ l,1x t-1+⋯+ϕ l,lx t-l+e l,t
where ϕ l,1,ϕ l,2,…,ϕ l,l are matrix coefficients, and e l,t is the vector of errors in the prediction. These coefficients may be rapidly computed using a recursive technique which requires, and simultaneously furnishes, a backward prediction equation:
x t-l-1=ψ l,1x t-l+ψ l,2x t-l+1+⋯+ψ l,lx t-1+f l,t
(in the univariate case ψ l,i=ϕ l,i).
The forward prediction equation coefficients, ϕ l,i, are of direct interest, together with the covariance matrix Dl of the prediction errors e l,t. The calculation of these quantities for a particular maximum equation lag l=L involves calculation of the same quantities for increasing values of l=1,2,…,L.
The quantities vl=det⁡Dl/det⁡Γ 0 may be viewed as generalized variance ratios, and provide a measure of the efficiency of prediction (the smaller the better). The reduction from v l-1 to vl which occurs on extending the order of the predictor to l may be represented as
vl=v l-1 1-ρl 2
where ρl 2 is a multiple squared partial autocorrelation coefficient associated with k 2 degrees of freedom.
Sample estimates of all the above quantities may be derived by using the series covariance matrices Cl, for l=1,2,…,L, in place of Γl. The best lag for prediction purposes may be chosen as that which yields the minimum final prediction error (FPE) criterion:
FPE l=vl× 1+l k 2/n 1-l k 2/n .
An alternative method of estimating the sample partial autoregression matrices is by using multivariate least squares to fit a series of multivariate autoregressive models of increasing order.

2.4.3 VARMA model estimation

The cross-correlation structure of a stationary multivariate time series may often be represented by a model with a small number of parameters belonging to the VARMA class. If the stationary series wt has been derived by transforming and/or differencing the original series xt, then wt is said to follow the VARMA model:
wt=ϕ 1w t-1+⋯+ϕpw t-p+εt-θ 1ε t-1-⋯-θqε t-q,
where εt is a vector of uncorrelated residual series (white noise) with zero mean and constant covariance matrix Σ, ϕ 1,ϕ 2,…,ϕp are the p autoregressive (AR) parameter matrices and θ 1,θ 2,…,θq are the q moving-average (MA) parameter matrices. If wt has a nonzero mean μ, then this can be allowed for by replacing wt,w t-1,… by wt-μ,w t-1-μ,… in the model.
A series generated by this model will only be stationary provided restrictions are placed on ϕ 1,ϕ 2,…,ϕp to avoid unstable growth of wt. These are stationarity constraints. The series εt may also be usefully interpreted as the linear innovations in wt, i.e., the error if wt were to be predicted using the information in all past values w t-1,w t-2,…, provided also that θ 1,θ 2,…,θq satisfy what are known as invertibility constraints. This allows the series εt to be generated by rewriting the model equation as
εt=wt-ϕ 1w t-1-⋯-ϕpw t-p+θ 1ε t-1+⋯+θqε t-q.
The method of maximum likelihood (ML) may be used to estimate the parameters of a specified VARMA model from the observed multivariate time series together with their standard errors and correlations.
The residuals from the model may be examined for the presence of autocorrelations as a check on the adequacy of the fitted model.

2.4.4 VARMA model forecasting

Forecasts of the series may be constructed using a multivariate version of the univariate method. Efficient methods are available for updating the forecasts each time new observations become available.

2.5 Cross-spectral Analysis

The relationship between two time series may be investigated in terms of their sinusoidal components at different frequencies. At frequency ω a component of yt of the form
Ry ω cos ωt-ϕy ω
has its amplitude Ry ω and phase lag ϕy ω estimated by
Ry ω e i ϕy ω=1 n∑t=1 n yt e iωt
and similarly for xt. In the univariate analysis only the amplitude was important – in the cross analysis the phase is important.

2.5.1 The sample cross-spectrum

This is defined by
f xy*ω=1 2 πn ∑t=1 n yt e iωt ∑t=1 n xt e-iωt .
It may be demonstrated that this is equivalently defined in terms of the sample cross-correlation function (CCF), r xy k, of the series as
f xy*ω=1 2 π ∑-n-1 n-1 c xy k e iωk
where c xy k=sxsyr xy k is the cross-covariance function.

2.5.2 The amplitude and phase spectrum

The cross-spectrum is specified by its real part or cospectrum c f*ω and imaginary part or quadrature spectrum q f*ω, but for the purpose of interpretation the cross-amplitude spectrum and phase spectrum are useful:
A*ω = f xy* ω ,   ϕ*ω = arg f xy * ω .
If the series xt and yt contain deterministic sinusoidal components of amplitudes Ry,Rx and phases ϕy,ϕx at frequency ω, then A*ω will have a peak of approximate width π/n and height n/2 π RyRx at that frequency, with corresponding phase ϕ*ω=ϕy-ϕx. This supplies no information that cannot be obtained from the two series separately. The statistical relationship between the series is better revealed when the series are purely stochastic and jointly stationary, in which case the expected value of f xy*ω converges with increasing sample size to the theoretical cross-spectrum
f xy ω = 1 2 π ∑ -∞ ∞ γ xy k e iωk
where γ xy k=cov xt,y t+k. The sample spectrum, as in the univariate case, does not converge to the theoretical spectrum without some form of smoothing which either implicitly (using a lag window) or explicitly (using a frequency window) averages the sample spectrum f xy ω* over wider bands of frequency to obtain a smoothed estimate f^xy ω.

2.5.3 The coherency spectrum

If there is no statistical relationship between the series at a given frequency, then f xy ω=0, and the smoothed estimate f^xy ω, will be close to 0. This is assessed by the squared coherency between the series:
W^ω=f^xy ω 2 f^xx ω f^yy ω
where f^xx ω is the corresponding smoothed univariate spectrum estimate for xt, and similarly for yt. The coherency can be treated as a squared multiple correlation. It is similarly invariant in theory not only to simple scaling of xt and yt, but also to filtering of the two series, and provides a useful test statistic for the relationship between autocorrelated series. Note that without smoothing,
f xy*ω 2=f xx*ω f yy*ω,
so the coherency is 1 at all frequencies, just as a correlation is 1 for a sample of size 1. Thus smoothing is essential for cross-spectrum analysis.

2.5.4 The gain and noise spectrum

If yt is believed to be related to xt by a linear lagged relationship as in Section 2.3, i.e.,
yt=v 0xt+v 1x t-1+v 2x t-2+⋯+nt,
then the theoretical cross-spectrum is
f xy ω =V ω f xx ω
where
V ω=G ω e iϕ ω=∑k=0∞vk e ikω
is called the frequency response of the relationship.
Thus if xt were a sinusoidal wave at frequency ω (and nt were absent), yt would be similar but multiplied in amplitude by G ω and shifted in phase by ϕ ω. Furthermore, the theoretical univariate spectrum
f yy ω=G ω 2 f xx ω+fn ω
where nt, with spectrum fn ω, is assumed independent of the input xt.
Cross-spectral analysis thus furnishes estimates of the gain
G^ ω= f^ xy ω / f^xx ω
and the phase
ϕ^ω=arg f^xy ω .
From these representations of the estimated frequency response V^ω, parametric transfer function (TF) models may be recognized and selected. The noise spectrum may also be estimated as
f^ y∣x ω= f^yy ω 1-W^ ω
a formula which reflects the fact that in essence a regression is being performed of the sinusoidal components of yt on those of xt over each frequency band.
Interpretation of the frequency response may be aided by extracting from V^ω estimates of the impulse response function (IRF) v^k. It is assumed that there is no anticipatory response between yt and xt, i.e., no coefficients vk with k=-1 or -2 are needed (their presence might indicate feedback between the series).

2.5.5 Cross-spectrum smoothing by lag window

The estimate of the cross-spectrum is calculated from the sample cross-variances as
f^xy ω=1 2 π ∑-M+S M+S w k-Sc xy k e iωk.
The lag window wk extends up to a truncation lag M as in the univariate case, but its centre is shifted by an alignment lag S usually chosen to coincide with the peak cross-correlation. This is equivalent to an alignment of the series for peak cross-correlation at lag 0, and reduces bias in the phase estimation.
The selection of the truncation lag M, which fixes the bandwidth of the estimate, is based on the same criteria as for univariate series, and the same choice of M and window shape should be used as in univariate spectrum estimation to obtain valid estimates of the coherency, gain, etc., and test statistics.

2.5.6 Direct smoothing of the cross-spectrum

The computations are exactly as for smoothing of the univariate spectrum except that allowance is made for an implicit alignment shift S between the series.

2.6 Kalman Filters

2.6.1 Linear State Space Models

Kalman filtering provides a method for the analysis of multidimensional time series. The underlying model is:
X t+1=AtXt+BtWt (8)
Yt=CtXt+Vt (9)
where Xt is the unobserved state vector, Yt is the observed measurement vector, Wt is the state noise, Vt is the measurement noise, At is the state transition matrix, Bt is the noise coefficient matrix and Ct is the measurement coefficient matrix at time t. The state noise and the measurement noise are assumed to be uncorrelated with zero mean and covariance matrices:
E Wt WtT = Qt   and   E Vt VtT = Rt .
If the system matrices At, Bt, Ct and the covariance matrices Qt,Rt are known then Kalman filtering can be used to compute the minimum variance estimate of the stochastic variable Xt.
The estimate of Xt given observations Y 1 to Y t-1 is denoted by X^ t∣t-1 with state covariance matrix E X^ t∣t-1 X^t∣t-1 T = P t∣t-1 while the estimate of Xt given observations Y 1 to Yt is denoted by X^ t∣t with covariance matrix E X^ t∣t X^t∣t T = P t∣t.
The update of the estimate, X^ t+1∣t , from time t to time t+1, is computed in two stages.
First, the update equations are
X^ t∣t = X^ t∣t-1 + Kt rt,   P t∣t= I- Kt Ct P t∣t-1
where the residual rt= Yt- Ct X t∣t-1 has an associated covariance matrix Ht = Ct P t∣t-1 CtT + Rt , and Kt is the Kalman gain matrix with
Kt= P t∣t-1 CtT Ht-1 .
The second stage is the one-step-ahead prediction equations given by
X^ t+1 ∣ t = At X^ t ∣ t ,   P t+1 ∣ t = At P t ∣ t AtT + Bt Qt BtT .
These two stages can be combined to give the one-step-ahead update-prediction equations
X^ t+1∣t = At X^ t∣t-1 + At Kt rt .
The above equations thus provide a method for recursively calculating the estimates of the state vectors X^ t∣t and X^ t+1∣t and their covariance matrices P t∣t and P t+1∣t from their previous values. This recursive procedure can be viewed in a Bayesian framework as being the updating of the prior by the data Yt.
The initial values X^ 1∣0 and P 1∣0 are required to start the recursion. For stationary systems, P 1∣0 can be computed from the following equation:
P 1∣0=A 1P 1∣0 A 1 T +B 1Q 1 B 1 T ,
which can be solved by iterating on the equation. For X^ 1∣0 the value E X can be used if it is available.
2.6.1.1 Computational methods
To improve the stability of the computations the square root algorithm is used. One recursion of the square root covariance filter algorithm which can be summarised as follows:
Rt 1/2 CtSt 0 0 AtSt Bt Qt 1/2 U= Ht 1/2 0 0 Gt S t+1 0
where U is an orthogonal transformation triangularizing the left-hand pre-array to produce the right-hand post-array, St is the lower triangular Cholesky factor of the state covariance matrix P t+1∣t, Qt 1/2 and Rt 1/2 are the lower triangular Cholesky factor of the covariance matrices Q and R and H 1/2 is the lower triangular Cholesky factor of the covariance matrix of the residuals. The relationship between the Kalman gain matrix, Kt, and Gt is given by
AtKt=Gt Ht 1/2 -1.
To improve the efficiency of the computations when the matrices At,Bt and Ct do not vary with time the system can be transformed to give a simpler structure. The transformed state vector is U*X where U* is the transformation that reduces the matrix pair A,C to lower observer Hessenberg form. That is, the matrix U* is computed such that the compound matrix
C U*T U*A U*T
is a lower trapezoidal matrix. The transformations need only be computed once at the start of a series, and the covariance matrices Qt and Rt can still be time-varying.
2.6.1.2 Model fitting and forecasting
If the state space model contains unknown parameters, θ, these can be estimated using maximum likelihood (ML). Assuming that Wt and Vt are normal variates the log-likelihood for observations Yt, for t=1,2,…,n, is given by
constant-12∑t=1 n ln det Ht-12∑t=1 t rtT Ht-1 rt.
Optimal estimates for the unknown model parameters θ can then be obtained by using a suitable optimizer routine to maximize the likelihood function.
Once the model has been fitted forecasting can be performed by using the one-step-ahead prediction equations. The one-step-ahead prediction equations can also be used to ‘jump over’ any missing values in the series.
2.6.1.3 Kalman filter and time series models
Many commonly used time series models can be written as state space models. A univariate ARMA p,q model can be cast into the following state space form:
xt =A x t-1+B εt wt =C xt
A= ϕ 1 1 ϕ 2 1 . . . . ϕ r-1 1 ϕr 0 0 . . 0 ,  B= -1 -θ 1 -θ 2 . . -θ r-1   and  CT= 1 0 0 . . 0 ,
where r=max p,q+1.
The representation for a k-variate ARMA p,q series (VARMA) is very similar to that given above, except now the state vector is of length kr and the ϕ and θ are now k×k matrices and the 1s in A, B and C are now the identity matrix of order k. If p<r or q+1<r then the appropriate ϕ or θ matrices are set to zero, respectively.
Since the compound matrix
C A
is already in lower observer Hessenberg form (i.e., it is lower trapezoidal with zeros in the top right-hand triangle) the invariant Kalman filter algorithm can be used directly without the need to generate a transformation matrix U*.

2.6.2 Nonlinear State Space Models

A nonlinear state space model, with additive noise, can, at time t, be described by:
x t+1 =F xt+vt yt =H xt+ut (18)
where xt represents the unobserved state vector of length mx and yt the observed measurement vector of length my. The process noise is denoted vt, which is assumed to have mean zero and covariance structure Σx, and the measurement noise by ut, which is assumed to have mean zero and covariance structure Σy. The two nonlinear functions, F and H may be time dependent. Two methods are commonly used to analyse nonlinear state space models: the Extended Kalman Filter (EKF) and the Unscented Kalman Filter (UKF).
The EKF solves the nonlinear state space model by first linearising the set of equations given in (18) using a first order taylor expansion around x^t (the estimate of the state vector at time t given the full data: y 1,y 2,…,yt) in the case of F and around x^t_ (the estimate of the state vector at time t given the partial data: y 1,y 1,…,y t-1) in the case of H. This leads to the linear state space model:
x t+1 ≈F′⁢xt+vt+F′-F x^t⁢x^t yt-H x^t_+H′⁢x^t_ ≈H′⁢xt+ut
where
F′ =∂F x∂x x=x^t H′ =∂H x∂x x=x^t_
This linear state space model can then be solved using the standard Kalman Filter. See Haykin (2001) for more details.
Unlike the EKF, the UKF of Julier and Uhlmann (1997) does not attempt to linearise the problem, rather it uses a minimal set of carefully chosen points, called sigma points, to capture the mean and covariance of the underlying Gaussian random variables. These points are then propagated through the nonlinear functions giving an estimate of the transformed mean and covariance. A brief description of the UKF can be found in Section 3 in G13EKF.

2.7 GARCH Models

2.7.1 ARCH models and their generalizations

Rather than modelling the mean (for example using regression models) or the autocorrelation (by using ARMA models) there are circumstances in which the variance of a time series needs to be modelled. This is common in financial data modelling where the variance (or standard deviation) is known as volatility. The ability to forecast volatility is a vital part in deciding the risk attached to financial decisions like portfolio selection. The basic model for relating the variance at time t to the variance at previous times is the autoregressive conditional heteroskedastic (ARCH) model. The standard ARCH model is defined as
yt ∣ ψ t-1 ∼ N 0,ht , ht = α 0+ ∑ i=1 q αi ε t-i 2 ,
where ψt is the information up to time t and ht is the conditional variance.
In a similar way to that in which autoregressive (AR) models were generalized to ARMA models the ARCH models have been generalized to a GARCH model; see Engle (1982), Bollerslev (1986) and Hamilton (1994)
ht = α 0 + ∑ i=1 q αi ε t-i 2 + ∑ i=1 p β h t-i .
This can be combined with a regression model:
yt=b 0+∑i= 1 k bi x it+εt,
where εt∣ψ t-1∼N 0,ht and where x it, for i=1,2,…,k, are the exogenous variables.
The above models assume that the change in variance, ht, is symmetric with respect to the shocks, that is, that a large negative value of ε t-1 has the same effect as a large positive value of ε t-1. A frequently observed effect is that a large negative value ε t-1 often leads to a greater variance than a large positive value. The following three asymmetric models represent this effect in different ways using the parameter γ as a measure of the asymmetry.
Type I AGARCH(p,q)
ht = α 0 + ∑ i=1 q αi ε t-i +γ 2 + ∑ i=1 p βi h t-i .
Type II AGARCH(p,q)
ht = α 0 + ∑ i=1 q αi ε t-i + γ ε t-i 2+ ∑ i=1 p βi h t-i .
GJR-GARCH(p,q), or Glosten, Jagannathan and Runkle GARCH (see Glosten et al. (1993))
ht = α 0 + ∑ i=1 q αi + γ I t-1 ε t-1 2 + ∑ i=1 p βi h t-i ,
where It=1 if εt<0 and It=0 if εt≥0.
The first assumes that the effects of the shocks are symmetric about γ rather than zero, so that for γ<0 the effect of negative shocks is increased and the effect of positive shocks is decreased. Both the Type II AGARCH and the GJR GARCH (see Glosten et al. (1993)) models introduce asymmetry by increasing the value of the coefficient of ε t-1 2 for negative values of ε t-1. In the case of the Type II AGARCH the effect is multiplicative while for the GJR GARCH the effect is additive.
Coefficient | ε t-1<0 | ε t-1>0
Type II AGARCH | αi 1-γ 2 | αi 1+γ 2
GJR GARCH | αi+γ | αi
(Note that in the case of GJR GARCH, γ needs to be positive to inflate variance after negative shocks while for Type I and Type II AGARCH, γ needs to be negative.)
A third type of GARCH model is the exponential GARCH (EGARCH). In this model the variance relationship is on the log scale and hence asymmetric.
ln ht = α 0 + ∑ i=1 q αi z t-i + ∑ i=1 q ϕi z t-i - E z t-i + ∑ i=1 p βi ln h t-i ,
where zt= εt ht and E z t-i denotes the expected value of z t-i.
Note that the ϕi terms represent a symmetric contribution to the variance while the αi terms give an asymmetric contribution.
Another common characteristic of financial data is that it is heavier in the tails (leptokurtic) than the Normal distribution. To model this the Normal distribution is replaced by a scaled Student's t-distribution (that is a Student's t-distribution standardized to have variance ht). The Student's t-distribution is such that the smaller the degrees of freedom the higher the kurtosis for degrees of freedom >4.

2.7.2 Fitting GARCH models

The models are fitted by maximizing the conditional log-likelihood. For the Normal distribution the conditional log-likelihood is
12∑i=1 T log hi+εi 2 hi .
For the Student's t-distribution the function is more complex. An approximation to the standard errors of the parameter estimates is computed from the Fisher information matrix.

2.8 Inhomogeneous Time Series

If we denote a generic univariate time series as a sequence of pairs of values zi,ti, for i=1,2,… where the z's represent an observed scalar value and the t's the time that the value was observed, then in a standard time series analysis, as discussed in other sections of this introduction, it is assumed that the series being analysed is homogeneous, that is the sampling times are regularly spaced with ti-t i-1=δ for some value δ. In many real world applications this assumption does not hold, that is, the series is inhomogeneous.
Standard time series analysis techniques cannot be used on an inhomogeneous series without first preprocessing the series to construct an artificial homogeneous series, by for example, resampling the series at regular intervals. Zumbach and Müller (2001) introduced a series of operators that can be used to extract robust information directly from the inhomogeneous time series. In this context, robust information means that the results should be essentially independent of minor changes to the sampling mechanism used when collecting the data, for example, changing a number of time stamps or adding or removing a few observations.
The basic operator available for inhomogeneous time series is the exponential moving average (EMA). This operator has a single parameter, τ, and is an average operator with an exponentially decaying kernel given by:
e -t/τ τ .
This gives rise to the following iterative formula:
EMA τ;z ti = μ ⁢ EMA τ;z t i-1 + ν-μ ⁢ z i-1 + 1-ν ⁢ zi
where
μ = e-α   and   α = ti - t i-1 τ .
The value of ν depends on the method of interpolation chosen. Three interpolation methods are available:
1. | Previous point: | ν=1.
2. | Linear: | ν= 1-μ / α .
3. | Next point: | ν=μ.
Given the EMA, a number of other operators can be defined, including:
(i) m-Iterated Exponential Moving Average, defined as
EMA τ,m;z = EMA τ ; EMA τ,m-1 ; z ​ where ​ EMA τ,1;z = EMA τ ; z .
(ii) Moving Average (MA), defined as
MA τ, m 1, m 2; z ti = 1 m 2 - m 1 +1 ∑ j=m 1 m 2 EMA τ~, j; z ti ​ where ​ τ~= 2⁢τ m 2+m 1
(iii) Moving Norm (MNorm), defined as
MNorm τ,m,p;z = MA τ,1,m; z p 1 / p
(iv) Moving Variance (MVar), defined as
MVar τ,m,p;z = MA τ,1,m; z - MA τ,1,m;z p
(v) Moving Standard Deviation (MSD), defined as
MSD τ,m,p;z = MA τ,1,m; z - MA τ,1,m;z p 1 / p
(vi) Differential ( Δ), defined as
Δ τ,α,β,γ;z = γ⁢ EMA α⁢τ,1;z + EMA α⁢τ,2;z - 2⁢ EMA α⁢β⁢τ,4;z
(vii) Volatility, defined as
Volatility τ,τ′,m,p;z = MNorm τ/2,m,p;Δ τ′;z
A discussion of each of these operators, their use and in some cases, alternative definitions, are given in Zumbach and Müller (2001).

3 Recommendations on Choice and Use of Available Routines

3.1 Univariate Analysis

The availability of routines for each of these four steps is given below.

3.1.1 ARMA-type Models

ARMA-type modelling usually follows the methodology made popular by Box and Jenkins. It consists of four steps: identification, model fitting, model checking and forecasting.
(a) Model identification
The routine G13AUF may be used in obtaining either a range-mean or standard deviation-mean plot for a series of observations, which may be useful in detecting the need for a variance-stabilizing transformation. G13AUF computes the range or standard deviation and the mean for successive groups of observations and G01AGF may then be used to produce a scatter plot of range against mean or of standard deviation against mean.
The routine G13AAF may be used to difference a time series. The N=n-d-s×D values of the differenced time series which extends for t=1+d+s×D,…,n are stored in the first N elements of the output array.
The routine G13ABF may be used for direct computation of the autocorrelations. It requires the time series as input, after optional differencing by G13AAF.
An alternative is to use G13CAF, which uses the fast Fourier transform (FFT) to carry out the convolution for computing the autocovariances. Circumstances in which this is recommended are
(i) | if the main aim is to calculate the smoothed sample spectrum;
(ii) | if the series length and maximum lag for the autocorrelations are both very large, in which case appreciable computing time may be saved.
For more precise recommendations, see Gentleman and Sande (1966). In this case the autocorrelations rk need to be obtained from the autocovariances ck by rk=ck/c 0.
The routine G13ACF computes the partial autocorrelation function (PACF) and prediction error variance estimates from an input autocorrelation function (ACF). Note that G13DNF, which is designed for multivariate time series, may also be used to compute the PACF together with χ 2 statistics and their significance levels.
Finite lag predictor coefficients are also computed by the routine G13ACF. It may have to be used twice, firstly with a large value for the maximum lag L in order to locate the optimum final prediction error (FPE) lag, then again with L reset to this lag.
The routine G13DXF may be used to check that the autoregressive (AR) part of the model is stationary and that the moving-average (MA) part is invertible.
(b) Model estimation
The routine G13ADF is used to compute preliminary estimates of the ARIMA model parameters, the sample autocorrelations of the appropriately differenced series being input. The model orders are required.
The main routine for parameter estimation for ARIMA models is G13AEF, and an easy-to-use version is G13AFF. Both these routines use the least squares criterion of estimation.
In some circumstances the use of G13BEF or G13DDF, which use maximum likelihood (ML), is recommended.
The routines require the time series values to be input, together with the ARIMA orders. Any differencing implied by the model is carried out internally. They also require the maximum number of iterations to be specified, and return the state set for use in forecasting.
G13AEF should be preferred to G13AFF for:
(i) | more information about the differenced series, its backforecasts and the intermediate series;
(ii) | greater control over the output at successive iterations;
(iii) | more detailed control over the search policy of the nonlinear least squares algorithm;
(iv) | more information about the first and second derivatives of the objective function during and upon completion of the iterations.
G13BEF is primarily designed for estimating relationships between time series. It is, however, easily used in a univariate mode for ARIMA model estimation. The advantage is that it allows (optional) use of the exact likelihood estimation criterion, which is not available in G13AEF or G13AFF. This is particularly recommended for models which have seasonal parameters, because it reduces the tendency of parameter estimates to become stuck at points on the parameter space boundary. The model parameters estimated in this routine should be passed over to G13AJF for use in univariate forecasting.
The routine G13DDF is primarily designed for fitting vector ARMA models to multivariate time series but may also be used in a univariate mode. It allows the use of either the exact or conditional likelihood estimation criterion, and allows you to fit non-multiplicative seasonal models which are not available in G13AEF, G13AFF or G13BEF.
(c) Model checking
G13ASF calculates the correlations in the residuals from a model fitted by either G13AEF or G13AFF. In addition the standard errors and correlations of the residual autocorrelations are computed along with a portmanteau test for model adequacy. G13ASF can be used after a univariate model has been fitted by G13BEF, but care must be taken in selecting the correct inputs to G13ASF. Note that if G13DDF has been used to fit a non-multiplicative seasonal model to a univariate series then G13DSF may be used to check the adequacy of the model.
(d) Forecasting using an ARIMA model
Given that the state set produced on estimation of the ARIMA model by either G13AEF or G13AFF has been retained, G13AHF can be used directly to construct forecasts for x n+1,x n+2,…, together with probability limits. If some further observations x n+1,x n+2,… have come to hand since model estimation (and there is no desire to re-estimate the model using the extended series), then G13AGF can be used to update the state set using the new observations, prior to forecasting from the end of the extended series. The original series is not required.
The routine G13AJF is provided for forecasting when the ARIMA model is known but the state set is unknown. For example, the model may have been estimated by a procedure other than the use of G13AEF or G13AFF, such as G13BEF. G13AJF constructs the state set and optionally constructs forecasts with probability limits. It is equivalent to a call to G13AEF with zero iterations requested, followed by an optional call to G13AHF, but it is much more efficient.

3.1.2 Exponential smoothing

A variety of different smoothing methods are provided by G13AMF, including; single exponential, Brown's double exponential, linear Holt (also called double exponential smoothing in some references), additive Holt–Winters and multiplicative Holt–Winters. The choice of smoothing method used depends on the characteristics of the time series. If the mean of the series is only slowly changing then single exponential smoothing may be suitable. If there is a trend in the time series, which itself may be slowly changing, then double exponential smoothing may be suitable. If there is a seasonal component to the time series, e.g., daily or monthly data, then one of the two Holt–Winters methods may be suitable.

3.1.3 Change point analysis

Four routines are available for change point analysis, two implementing the PELT algorithm (G13NAF and G13NBF) and two binary segmentation (G13NDF and G13NEF). Of these, G13NAF and G13NDF have six pre-defined cost functions based on the log-likelihood of the Normal, Gamma, Exponential and Poisson distributions. In the case of the Normal distribution changes in the mean, standard deviation or both can be investigated. The remaining two routines, G13NBF and G13NEF take a user-supplied cost function.
Binary segmentation only returns an approximate solution to the change point problem as defined in equation (5). It is therefore recommended that the PELT algorithm is used in most cases. However, for long time series the binary segmentation algorithm may give a marked improvement in terms of speed especially if the maximum depth for the iterative process (MDEPTH) is set to a low value.

3.2 Univariate Spectral Analysis

Two routines are available, G13CAF carrying out smoothing using a lag window and G13CBF carrying out direct frequency domain smoothing. Both can take as input the original series, but G13CAF alone can use the sample autocovariances as alternative input. This has some computational advantage if a variety of spectral estimates needs to be examined for the same series using different amounts of smoothing.
However, the real choice in most cases will be which of the four shapes of lag window in G13CAF to use, or whether to use the trapezium frequency window of G13CBF. The references may be consulted for advice on this, but the two most recommended lag windows are the Tukey and Parzen. The Tukey window has a very small risk of supplying negative spectrum estimates; otherwise, for the same bandwidth, both give very similar results, though the Parzen window requires a higher truncation lag (more autocorrelation function (ACF) values).
The frequency window smoothing procedure of G13CBF with a trapezium shape parameter p≃12 generally gives similar results for the same bandwidth as lag window methods with a slight advantage of somewhat less distortion around sharp peaks, but suffering a rather less smooth appearance in fine detail.

3.3 Linear Lagged Relationships Between Time Series

The availability of routines for each of four steps: identification, model fitting, model checking and forecasting, is given below.
(a) Model identification
Normally use G13BCF for direct computation of cross-correlations, from which cross-covariances may be obtained by multiplying by sysx, and impulse response estimates (after prewhitening) by multiplying by sy/sx, where sy,sx are the sample standard deviations of the series.
An alternative is to use G13CCF, which exploits the fast Fourier transform (FFT) to carry out the convolution for computing cross-covariances. The criteria for this are the same as given in Section 3.1.1 for calculation of autocorrelations. The impulse response function may also be computed by spectral methods without prewhitening using G13CGF.
G13BAF may be used to prewhiten or filter a series by an ARIMA model.
G13BBF may be used to filter a time series using a transfer function model.
(b) Estimation of input-output model parameters
The routine G13BDF is used to obtain preliminary estimates of transfer function model parameters. The model orders and an estimate of the impulse response function (see Section 3.2) are required.
The simultaneous estimation of the transfer function model parameters for the inputs, and ARIMA model parameters for the output, is carried out by G13BEF.
This routine requires values of the output and input series, and the orders of all the models. Any differencing implied by the model is carried out internally.
The routine also requires the maximum number of iterations to be specified, and returns the state set for use in forecasting.
(c) Input-output model checking
The routine G13ASF, primarily designed for univariate time series, can be used to test the residuals from an input-output model.
(d) Forecasting using an input-output model
Given that the state set produced on estimation of the model by G13BEF has been retained, the routine G13BHF can be used directly to construct forecasts of the output series. Future values of the input series (possibly forecasts previously obtained using G13AHF) are required.
If further observations of the output and input series have become available since model estimation (and there is no desire to re-estimate the model using the extended series) then G13BGF can be used to update the state set using the new observations prior to forecasting from the end of the extended series. The original series are not required.
The routine G13BJF is provided for forecasting when the multi-input model is known, but the state set is unknown. The set of output and input series must be supplied to the routine which then constructs the state set (for future use with G13BGF and/or G13BHF) and also optionally constructs forecasts of the output series in a similar manner to G13BHF.
In constructing probability limits for the forecasts, it is possible to allow for the fact that future input series values may themselves have been calculated as forecasts using ARIMA models. Use of this option requires that these ARIMA models be supplied to the routine.
(e) Filtering a time series using a transfer function model
The routine for this purpose is G13BBF.

3.4 Multivariate Time Series

The availability of routines for each of four steps: identification, model fitting, model checking and forecasting, is given below.
(a) Model identification
The routine G13DLF may be used to difference the series. You must supply the differencing parameters for each component of the multivariate series. The order of differencing for each individual component does not have to be the same. The routine may also be used to apply a log or square root transformation to the components of the series.
The routine G13DMF may be used to calculate the sample cross-correlation or cross-covariance matrices. It requires a set of time series as input. You may request either the cross-covariances or cross-correlations.
The routine G13DNF computes the partial lag correlation matrices from the sample cross-correlation matrices computed by G13DMF, and the routine G13DPF computes the least squares estimates of the partial autoregression matrices and their standard errors. Both routines compute a series of χ 2 statistics that aid the determination of the order of a suitable autoregressive model. G13DBF may also be used in the identification of the order of an autoregressive model. The routine computes multiple squared partial autocorrelations and predictive error variance ratios from the sample cross-correlations or cross-covariances computed by G13DMF.
The routine G13DXF may be used to check that the autoregressive part of the model is stationary and that the moving-average part is invertible.
(b) Estimation of VARMA model parameters
The routine for this purpose is G13DDF. This routine requires a set of time series to be input, together with values for p and q. You must also specify the maximum number of likelihood evaluations to be permitted and which parameters (if any) are to be held at their initial (user-supplied) values. The fitting criterion is either exact maximum likelihood (ML) or conditional maximum likelihood.
G13DDF is primarily designed for estimating relationships between time series. It may, however, easily be used in univariate mode for non-seasonal and non-multiplicative seasonal ARIMA model estimation. The advantage is that it allows (optional) use of the exact maximum likelihood (ML) estimation criterion, which is not available in either G13AEF or G13AFF. The conditional likelihood option is recommended for those models in which the parameter estimates display a tendency to become stuck at points on the boundary of the parameter space. When one of the series is known to be influenced by all the others, but the others in turn are mutually independent and do not influence the output series, then G13BEF (the transfer function (TF) model fitting routine) may be more appropriate to use.
(c) VARMA model checking
G13DSF calculates the cross-correlation matrices of residuals for a model fitted by G13DDF. In addition the standard errors and correlations of the residual correlation matrices are computed along with a portmanteau test for model adequacy.
(d) Forecasting using a VARMA model
The routine G13DJF may be used to construct a chosen number of forecasts using the model estimated by G13DDF. The standard errors of the forecasts are also computed. A reference vector is set up by G13DJF so that should any further observations become available the existing forecasts can be efficiently updated using G13DKF. On a call to G13DKF the reference vector itself is also updated so that G13DKF may be called again each time new observations are available.

3.5 Cross-spectral Analysis

Two routines are available for the main step in cross-spectral analysis. To compute the cospectrum and quadrature spectrum estimates using smoothing by a lag window, G13CCF should be used. It takes as input either the original series or cross-covariances which may be computed in a previous call of the same routine or possibly using results from G13BCF. As in the univariate case, this gives some advantage if estimates for the same series are to be computed with different amounts of smoothing.
The choice of window shape will be determined as the same as that which has already been used in univariate spectrum estimation for the series.
For direct frequency domain smoothing, G13CDF should be used, with similar consideration for the univariate estimation in choice of degree of smoothing.
The cross-amplitude and squared coherency spectrum estimates are calculated, together with upper and lower confidence bounds, using G13CEF. For input the cross-spectral estimates from either G13CCF or G13CDF and corresponding univariate spectra from either G13CAF or G13CBF are required.
The gain and phase spectrum estimates are calculated together with upper and lower confidence bounds using G13CFF. The required input is as for G13CEF above.
The noise spectrum estimates and impulse response function estimates are calculated together with multiplying factors for confidence limits on the former, and the standard error for the latter, using G13CGF. The required input is again the same as for G13CEF above.

3.6 Kalman Filtering

3.6.1 Linear state space models

Two routines are available for analysing a linear state space model using Kalman filtering: G13EAF for time varying systems and G13EBF for time invariant systems. The latter will optionally compute the required transformation to lower observer Hessenberg form. Both these routines return the Cholesky factor of the residual covariance matrix, Ht, with the Cholesky factor of the state covariance matrix S t+1 and the Kalman gain matrix, Kt pre-multiplied by At; in the case of G13EBF these may be for the transformed system. To compute the updated state vector and the residual vector the required matrix-vector multiplications can be performed by F06PAF (DGEMV).

3.6.2 Nonlinear state space models

Two routines are available for analysing a nonlinear state space model: G13EJF and G13EKF. The difference between the two routines is how the nonlinear functions, F and H are supplied, with G13EJF using reverse communication and G13EKF using direct communication. See Section 3.3.3 in How to Use the NAG Library and its Documentation for a description of the terms reverse and direct communication.
As well as having the additional flexibility inherent in reverse communication routines G13EJF also offers an alternative method of generating the sigma points utilized by the Unscented Kalman Filter (UKF), potentially allowing for additional information to be propagated through the state space model. However, due to the increased complexity of the interface it is recommended that G13EKF is used unless this additional flexibility is definitely required.

3.7 GARCH Models

The main choice in selecting a type of GARCH model is whether the data is symmetric or asymmetric and if asymmetric what form of asymmetry should be included in the model.
A symmetric ARCH or GARCH model can be fitted by G13FAF and the volatility forecast by G13FBF. For asymmetric data the choice is between the type of asymmetry as described in Section 2.7.
GARCH Type | Fit | Forecast
Type I | G13FAF | G13FBF
Type II | G13FCF | G13FDF
GJR | G13FEF | G13FFF
EGARCH | G13FGF | G13FHF
All routines allow the option of including regressor variables in the model and the choice between Normal and Student's t-distribution for the errors.

3.8 Inhomogeneous Time Series

The following routines deal with inhomogeneous time series, G13MEF, G13MFF and G13MGF.
Both G13MEF and G13MFF calculate the m-iterated exponential moving average (EMA). In most cases G13MEF can be used, which returns EMA τ,m;z for a given value of m, overwriting the input data. Sometimes it is advantageous to have access to the intermediate results, for example when calculating the differential operator, in which case G13MFF can be used, which can return EMA τ,i;z , for i=1,2,…,m. G13MFF can also be used if you do not wish to overwrite the input data.
The last routine, G13MGF should be used if you require the moving average, (MA), moving norm (MNorm), moving variance (MVar) or moving standard deviation (MSD). Other operators can be calculated by calling a combination of these three routines and the use of simple mathematics (additions, subtractions, etc.).

3.9 Time Series Simulation

There are routines available in Chapter G05 for generating a realization of a time series from a specified model: G05PHF for univariate time series and G05PJF for multivariate time series. There is also a suite of routines for simulating GARCH models: G05PDF, G05PEF, G05PFF and G05PGF. The routine G05PMF can be used to simulate data from an exponential smoothing model.

4 Functionality Index

ARMA modelling,
ACF G13ABF
diagnostic checking G13ASF
Dickey–Fuller unit root test G13AWF
differencing G13AAF
estimation (comprehensive) G13AEF
estimation (easy-to-use) G13AFF
forecasting from fully specified model G13AJF
forecasting from state set G13AHF
mean/range G13AUF
PACF G13ACF
preliminary estimation G13ADF
update state set G13AGF
Change point,
detection,
binary segmentation G13NDF
binary segmentation,
user supplied cost function G13NEF
PELT G13NAF
PELT,
user supplied cost function G13NBF
Exponential smoothing G13AMF
GARCH,
EGARCH,
fitting G13FGF
forecasting G13FHF
GJR GARCH,
fitting G13FEF
forecasting G13FFF
symmetric or type I AGARCH,
fitting G13FAF
forecasting G13FBF
type II AGARCH,
fitting G13FCF
forecasting G13FDF
Inhomogenous series,
iterated exponential moving average,
final value only returned G13MEF
intermediate values returned G13MFF
moving average G13MGF
Kalman,
filter,
time invariant,
square root covariance G13EBF
time varying,
square root covariance G13EAF
unscented G13EKF
unscented (reverse communication) G13EJF
Spectral analysis
Bivariate,
Bartlett, Tukey, Parzen windows G13CCF
cross amplitude spectrum G13CEF
direct smoothing G13CDF
gain and phase G13CFF
noise spectrum G13CGF
Univariate,
Bartlett, Tukey, Parzen windows G13CAF
direct smoothing G13CBF
Transfer function modelling,
cross-correlations G13BCF
filtering G13BBF
fitting G13BEF
forecasting from fully specified model G13BJF
forecasting from state set G13BHF
preliminary estimation G13BDF
pre-whitening G13BAF
update state set G13BGF
Vector ARMA,
cross-correlations G13DMF
diagnostic checks G13DSF
differencing G13DLF
fitting G13DDF
forecasting G13DJF
partial autoregression matrices G13DPF
partial correlation matrices G13DNF
squared partial autocorrelations G13DBF
update forecast G13DKF
zeros of ARIMA operator G13DXF

5 Auxiliary Routines Associated with Library Routine Arguments

G13AFZ nagf_tsa_uni_arima_estim_sample_piv
See the description of the argument PIV in G13AEF.

6 Routines Withdrawn or Scheduled for Withdrawal

The following lists all those routines that have been withdrawn since Mark 19 of the Library or are scheduled for withdrawal at one of the next two marks.
Withdrawn Routine | Mark of Withdrawal | Replacement Routine(s)
G13DCF | 24 | G13DDF

7 References

Akaike H (1971) Autoregressive model fitting for control Ann. Inst. Statist. Math. 23 163–180
Bollerslev T (1986) Generalised autoregressive conditional heteroskedasticity Journal of Econometrics 31 307–327
Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day
Engle R (1982) Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation Econometrica 50 987–1008
Gentleman W S and Sande G (1966) Fast Fourier transforms for fun and profit Proc. Joint Computer Conference, AFIPS 29 563–578
Glosten L, Jagannathan R and Runkle D (1993) Relationship between the expected value and the volatility of nominal excess return on stocks Journal of Finance 48 1779–1801
Hamilton J (1994) Time Series Analysis Princeton University Press
Haykin S (2001) Kalman Filtering and Neural Networks John Wiley and Sons
Heyse J F and Wei W W S (1985) The partial lag autocorrelation function Technical Report No. 32 Department of Statistics, Temple University, Philadelphia
Julier S J and Uhlmann J K (1997) A new extension of the Kalman Filter to nonlinear systems International Symposium for Aerospace/Defense, Sensing, Simulation and Controls (Volume 3) 26
Killick R, Fearnhead P and Eckely I A (2012) Optimal detection of changepoints with a linear computational cost Journal of the American Statistical Association 107:500 1590–1598
Tiao G C and Box G E P (1981) Modelling multiple time series with applications J. Am. Stat. Assoc. 76 802–816
Wei W W S (1990) Time Series Analysis: Univariate and Multivariate Methods Addison–Wesley
Zumbach G O and Müller U A (2001) Operators on inhomogeneous time series International Journal of Theoretical and Applied Finance 4(1) 147–178
G13 Chapter Contents
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13MEF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13MEF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13MEF calculates the iterated exponential moving average for an inhomogeneous time series.

2 Specification

SUBROUTINE G13MEF ( NB, IEMA, T, TAU, M, SINIT, INTER, PN, RCOMM, LRCOMM, IFAIL)
INTEGER | NB, M, INTER(2), PN, LRCOMM, IFAIL
REAL (KIND=nag_wp) | IEMA(NB), T(NB), TAU, SINIT(M+2), RCOMM(LRCOMM)

3 Description

G13MEF calculates the iterated exponential moving average for an inhomogeneous time series. The time series is represented by two vectors of length n; a vector of times, t; and a vector of values, z. Each element of the time series is therefore composed of the pair of scalar values ti,zi, for i=1,2,…,n. Time can be measured in any arbitrary units, as long as all elements of t use the same units.
The exponential moving average (EMA), with parameter τ, is an average operator, with the exponentially decaying kernel given by
e -ti/τ τ .
The exponential form of this kernel gives rise to the following iterative formula for the EMA operator (see Zumbach and Müller (2001)):
EMA τ;z ti = μ ⁢ EMA τ;z t i-1 + ν-μ ⁢ z i-1 + 1-ν ⁢ zi
where
μ = e-α   and   α = ti - t i-1 τ .
The value of ν depends on the method of interpolation chosen. G13MEF gives the option of three interpolation methods:
1. | Previous point: | ν=1;
2. | Linear: | ν= 1-μ / α ;
3. | Next point: | ν=μ.
The m-iterated exponential moving average, EMA τ,m;zti, m>1, is defined using the recursive formula:
EMA τ,m;z = EMA τ ; EMA τ,m-1 ; z
with
EMA τ,1;z = EMA τ ; z .
For large datasets or where all the data is not available at the same time, z and t can be split into arbitrary sized blocks and G13MEF called multiple times.

4 References

Dacorogna M M, Gencay R, Müller U, Olsen R B and Pictet O V (2001) An Introduction to High-frequency Finance Academic Press
Zumbach G O and Müller U A (2001) Operators on inhomogeneous time series International Journal of Theoretical and Applied Finance 4(1) 147–178

5 Arguments

1:   NB – INTEGERInput
On entry: b, the number of observations in the current block of data. The size of the block of data supplied in IEMA and T can vary; therefore NB can change between calls to G13MEF.
Constraint: NB≥0.
2:   IEMA NB – REAL (KIND=nag_wp) arrayInput/Output
On entry: zi, the current block of observations, for i=k+1,…,k+b, where k is the number of observations processed so far, i.e., the value supplied in PN on entry.
On exit: the iterated EMA, with IEMA i = EMA τ,m;z ti .
3:   T NB – REAL (KIND=nag_wp) arrayInput
On entry: ti, the times for the current block of observations, for i=k+1,…,k+b, where k is the number of observations processed so far, i.e., the value supplied in PN on entry.
If ti≤t i-1, IFAIL=31 will be returned, but G13MEF will continue as if t was strictly increasing by using the absolute value.
4:   TAU – REAL (KIND=nag_wp)Input
On entry: τ, the argument controlling the rate of decay, which must be sufficiently large that e-α, α=ti-t i-1/τ can be calculated without overflowing, for all i.
Constraint: TAU>0.0.
5:   M – INTEGERInput
On entry: m, the number of times the EMA operator is to be iterated.
Constraint: M≥1.
6:   SINIT M+2 – REAL (KIND=nag_wp) arrayInput
On entry: if PN=0, the values used to start the iterative process, with
  • SINIT 1=t 0,
  • SINIT 2=z 0,
  • SINIT j+2= EMA τ,j ; z t 0 , for j=1,2,…,M.
If PN≠0, SINIT is not referenced.
7:   INTER 2 – INTEGER arrayInput
On entry: the type of interpolation used with INTER 1 indicating the interpolation method to use when calculating EMA τ,1;z and INTER 2 the interpolation method to use when calculating EMA τ,j;z, j>1.
Three types of interpolation are possible:
INTER i=1
Previous point, with ν=1.
INTER i=2
Linear, with ν=1-μ/α.
INTER i=3
Next point, ν=μ.
Zumbach and Müller (2001) recommend that linear interpolation is used in second and subsequent iterations, i.e., INTER 2=2, irrespective of the interpolation method used at the first iteration, i.e., the value of INTER 1.
Constraint: INTER i=1, 2 or 3, for i=1,2.
8:   PN – INTEGERInput/Output
On entry: k, the number of observations processed so far. On the first call to G13MEF, or when starting to summarise a new dataset, PN must be set to 0. On subsequent calls it must be the same value as returned by the last call to G13MEF.
On exit: k+b, the updated number of observations processed so far.
Constraint: PN≥0.
9:   RCOMM LRCOMM – REAL (KIND=nag_wp) arrayCommunication Array
On entry: communication array, used to store information between calls to G13MEF. If LRCOMM=0, RCOMM is not referenced, PN must be set to 0 and all the data must be supplied in one go.
10:   LRCOMM – INTEGERInput
On entry: the dimension of the array RCOMM as declared in the (sub)program from which G13MEF is called.
Constraint: LRCOMM=0 or LRCOMM≥M+20.
11:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=11
On entry, NB=value.
Constraint: NB≥0.
IFAIL=31
On entry, i=value, T i-1=value and T i=value.
Constraint: T should be strictly increasing.
IFAIL=32
On entry, i=value, T i-1=value and T i=value.
Constraint: T i≠T i-1 if linear interpolation is being used.
IFAIL=41
On entry, TAU=value.
Constraint: TAU>0.0.
IFAIL=42
On entry, TAU=value.
On entry at previous call, TAU=value.
Constraint: if PN>0 then TAU must be unchanged since previous call.
IFAIL=51
On entry, M=value.
Constraint: M≥1.
IFAIL=52
On entry, M=value.
On entry at previous call, M=value.
Constraint: if PN>0 then M must be unchanged since previous call.
IFAIL=71
On entry, INTER 1=value.
Constraint: INTER 1=1, 2 or 3.
IFAIL=72
On entry, INTER 2=value.
Constraint: INTER 2=1, 2 or 3.
IFAIL=73
On entry, INTER 1=value and INTER 2=value.
On entry at previous call, INTER 1=value, INTER 2=value.
Constraint: if PN≠0, INTER must be unchanged since the previous call.
IFAIL=81
On entry, PN=value.
Constraint: PN≥0.
IFAIL=82
On entry, PN=value.
On exit from previous call, PN=value.
Constraint: if PN>0 then PN must be unchanged since previous call.
IFAIL=91
RCOMM has been corrupted between calls.
IFAIL=101
On entry, PN=0, LRCOMM=value and M=value.
Constraint: if PN=0, LRCOMM=0 or LRCOMM≥M+20.
IFAIL=102
On entry, PN≠0, LRCOMM=value and M=value.
Constraint: if PN≠0, LRCOMM≥M+20.
IFAIL=301
Truncation occurred to avoid overflow, check for extreme values in T, IEMA or for TAU. Results are returned using the truncated values.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

G13MEF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13MEF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

Approximately 4⁢m real elements are internally allocated by G13MEF.
The more data you supply to G13MEF in one call, i.e., the larger NB is, the more efficient the routine will be, particularly if the routine is being run using more than one thread.
Checks are made during the calculation of α to avoid overflow. If a potential overflow is detected the offending value is replaced with a large positive or negative value, as appropriate, and the calculations performed based on the replacement values. In such cases IFAIL=301 is returned. This should not occur in standard usage and will only occur if extreme values of IEMA, T or TAU are supplied.

10 Example

The example reads in a simulated time series, t,z and calculates the iterated exponential moving average.

10.1 Program Text

Program Text (g13mefe.f90)

10.2 Program Data

Program Data (g13mefe.d)

10.3 Program Results

Program Results (g13mefe.r)

This example plot shows the exponential moving average for the same data using three different values of τ and illustrates the effect on the EMA of altering this argument.
GnuplotProduced by GNUPLOT 4.6 patchlevel 3 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1 0 10 20 30 40 50 60 70 80 90 100 Value Time Example Program Simulated inhomogeneous time series and the corresponding EMA(τ,2;y) for a variety of values of τ gnuplot_plot_1 τ = 8.0 gnuplot_plot_2 τ = 2.0 gnuplot_plot_3 τ = 0.5 gnuplot_plot_4
G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13MFF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13MFF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13MFF calculates the iterated exponential moving average for an inhomogeneous time series, returning the intermediate results.

2 Specification

SUBROUTINE G13MFF ( SORDER, NB, Z, IEMA, LDIEMA, T, TAU, M1, M2, SINIT, INTER, FTYPE, P, X, PN, RCOMM, LRCOMM, IFAIL)
INTEGER | SORDER, NB, LDIEMA, M1, M2, INTER(2), FTYPE, PN, LRCOMM, IFAIL
REAL (KIND=nag_wp) | Z(NB), IEMA(LDIEMA,*), T(NB), TAU, SINIT(M2+2), P, X(*), RCOMM(LRCOMM)

3 Description

G13MFF calculates the iterated exponential moving average for an inhomogeneous time series. The time series is represented by two vectors of length n: a vector of times, t; and a vector of values, z. Each element of the time series is therefore composed of the pair of scalar values ti,zi, for i=1,2,…,n. Time can be measured in any arbitrary units, as long as all elements of t use the same units.
The exponential moving average (EMA), with parameter τ, is an average operator, with the exponentially decaying kernel given by
e -ti/τ τ .
The exponential form of this kernel gives rise to the following iterative formula (Zumbach and Müller (2001)) for the EMA operator:
EMA τ ; y ti = μ ⁢ EMA τ;y t i-1 + ν-μ ⁢ y i-1 + 1-ν ⁢ yi
where
μ = e-α   and   α = ti - t i-1 τ .
The value of ν depends on the method of interpolation chosen and the relationship between y and the input series z depends on the transformation function chosen. G13MFF gives the option of three interpolation methods:
1. | Previous point: | ν=1;
2. | Linear: | ν= 1-μ / α ;
3. | Next point: | ν=μ.
and three transformation functions:
1. | Identity: | yi = zi p ;
2. | Absolute value: | yi = zi p ;
3. | Absolute difference: | yi = zi - xi p ;
where the notation p is used to denote the integer nearest to p. In the case of the absolute difference x is a user-supplied vector of length n and therefore each element of the time series is composed of the triplet of scalar values, ti,zi,xi.
The m-iterated exponential moving average, EMA τ,m;yti, is defined using the recursive formula:
EMA τ,m ; y ti = EMA τ ; EMA τ,m-1 ; y ti ti
with
EMA τ,1;y ti = EMA τ;y ti .
For large datasets or where all the data is not available at the same time, z,t and, where required, x can be split into arbitrary sized blocks and G13MFF called multiple times.

4 References

Dacorogna M M, Gencay R, Müller U, Olsen R B and Pictet O V (2001) An Introduction to High-frequency Finance Academic Press
Zumbach G O and Müller U A (2001) Operators on inhomogeneous time series International Journal of Theoretical and Applied Finance 4(1) 147–178

5 Arguments

1:   SORDER – INTEGERInput
On entry: determines the storage order of output returned in IEMA.
Constraint: SORDER=1 or 2.
2:   NB – INTEGERInput
On entry: b, the number of observations in the current block of data. At each call the size of the block of data supplied in Z, T and X can vary; therefore NB can change between calls to G13MFF.
Constraint: NB≥0.
3:   Z NB – REAL (KIND=nag_wp) arrayInput
On entry: zi, the current block of observations, for i=k+1,…,k+b, where k is the number of observations processed so far, i.e., the value supplied in PN on entry.
Constraint: if FTYPE=1 or 2 and P<0.0, Z i≠0, for i=1,2,…,NB.
4:   IEMA LDIEMA* – REAL (KIND=nag_wp) arrayOutput
Note: the second dimension of the array IEMA must be at least M2-M1+1 if SORDER=1, otherwise at least NB.
On exit: the iterated exponential moving average.
If SORDER=1, IEMA ij = EMA τ,j+M1-1 ; y t i+k .
If SORDER=2, IEMA ji = EMA τ,j+M1-1 ; y t i+k .
For i=1,2,…,NB, j=1,2,…,M2-M1+1 and k is the number of observations processed so far, i.e., the value supplied in PN on entry.
5:   LDIEMA – INTEGERInput
On entry: the first dimension of the array IEMA as declared in the (sub)program from which G13MFF is called.
Constraints:
  • if SORDER=1, LDIEMA≥NB;
  • otherwise LDIEMA≥M2-M1+1.
6:   T NB – REAL (KIND=nag_wp) arrayInput
On entry: ti, the times for the current block of observations, for i=k+1,…,k+b, where k is the number of observations processed so far, i.e., the value supplied in PN on entry.
If ti≤t i-1, IFAIL=61 will be returned, but G13MFF will continue as if t was strictly increasing by using the absolute value.
7:   TAU – REAL (KIND=nag_wp)Input
On entry: τ, the parameter controlling the rate of decay. τ must be sufficiently large that e-α, α=ti-t i-1/τ can be calculated without overflowing, for all i.
Constraint: TAU>0.0.
8:   M1 – INTEGERInput
On entry: the minimum number of times the EMA operator is to be iterated.
Constraint: M1≥1.
9:   M2 – INTEGERInput
On entry: the maximum number of times the EMA operator is to be iterated. Therefore G13MFF returns EMA τ,m;y , for m=M1,M1+1,…,M2.
Constraint: M2≥M1.
10:   SINIT M2+2 – REAL (KIND=nag_wp) arrayInput
On entry: if PN=0, the values used to start the iterative process, with
  • SINIT 1=t 0,
  • SINIT 2=y 0,
  • SINIT j+2= EMA τ,j ; y t 0 , j=1,2,…,M2.
If PN≠0 then SINIT is not referenced.
Constraint: if FTYPE≠1, SINIT j≥0, for j=2,3,…,M2+2.
11:   INTER 2 – INTEGER arrayInput
On entry: the type of interpolation used with INTER 1 indicating the interpolation method to use when calculating EMA τ,1;z and INTER 2 the interpolation method to use when calculating EMA τ,j;z, j>1.
Three types of interpolation are possible:
INTER i=1
Previous point, with ν=1.
INTER i=2
Linear, with ν=1-μ/α.
INTER i=3
Next point, ν=μ.
Zumbach and Müller (2001) recommend that linear interpolation is used in second and subsequent iterations, i.e., INTER 2=2, irrespective of the interpolation method used at the first iteration, i.e., the value of INTER 1.
Constraint: INTER i=1, 2 or 3, for i=1,2.
12:   FTYPE – INTEGERInput
On entry: the function type used to define the relationship between y and z when calculating EMA τ,1;y. Three functions are provided:
FTYPE=1
The identity function, with yi = zi p .
FTYPE=2
The absolute value, with yi = zi p .
FTYPE=3
The absolute difference, with yi = zi - xi p , where the vector x is supplied in X.
Constraint: FTYPE=1, 2 or 3.
13:   P – REAL (KIND=nag_wp)Input/Output
On entry: p, the power used in the transformation function.
On exit: if FTYPE=1, then p, the actual power used in the transformation function is returned, otherwise P is unchanged.
Constraint: P≠0.
14:   X* – REAL (KIND=nag_wp) arrayInput
Note: the dimension of the array X must be at least NB if FTYPE=3.
On entry: if FTYPE=3, xi, the vector used to shift the current block of observations, for i=k+1,…,k+b, where k is the number of observations processed so far, i.e., the value supplied in PN on entry.
If FTYPE≠3 then X is not referenced.
Constraint: if FTYPE=3 and P<0, X i≠Z i, for i=1,2,…,NB.
15:   PN – INTEGERInput/Output
On entry: k, the number of observations processed so far. On the first call to G13MFF, or when starting to summarise a new dataset, PN must be set to 0. On subsequent calls it must be the same value as returned by the last call to G13MFF.
On exit: k+b, the updated number of observations processed so far.
Constraint: PN≥0.
16:   RCOMM LRCOMM – REAL (KIND=nag_wp) arrayCommunication Array
On entry: communication array, used to store information between calls to G13MFF. If LRCOMM=0, RCOMM is not referenced, PN must be set to 0 and all the data must be supplied in one go.
17:   LRCOMM – INTEGERInput
On entry: the dimension of the array RCOMM as declared in the (sub)program from which G13MFF is called.
Constraint: LRCOMM=0 or LRCOMM≥M2+20.
18:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=11
On entry, SORDER=value.
Constraint: SORDER=1 or 2.
IFAIL=21
On entry, NB=value.
Constraint: NB≥0.
IFAIL=51
On entry, SORDER=1, LDIEMA=value and NB=value.
Constraint: LDIEMA≥NB.
On entry, SORDER=2, LDIEMA=value and M2-M1+1=value.
Constraint: LDIEMA≥M2-M1+1.
IFAIL=61
On entry, i=value, T i-1=value and T i=value.
Constraint: T should be strictly increasing.
IFAIL=62
On entry, i=value, T i-1=value and T i=value.
Constraint: T i≠T i-1 if linear interpolation is being used.
IFAIL=71
On entry, TAU=value.
Constraint: TAU>0.0.
IFAIL=72
On entry, TAU=value.
On entry at previous call, TAU=value.
Constraint: if PN>0 then TAU must be unchanged since previous call.
IFAIL=81
On entry, M1=value.
Constraint: M1≥1.
IFAIL=82
On entry, M1=value.
On entry at previous call, M1=value.
Constraint: if PN>0 then M1 must be unchanged since previous call.
IFAIL=91
On entry, M1=value and M2=value.
Constraint: M2≥M1.
IFAIL=92
On entry, M2=value.
On entry at previous call, M2=value.
Constraint: if PN>0 then M2 must be unchanged since previous call.
IFAIL=101
On entry, FTYPE≠1, j=value and SINIT j=value.
Constraint: if FTYPE≠1, SINIT j≥0.0, for j=2,3,…,M2+2.
IFAIL=111
On entry, INTER 1=value.
Constraint: INTER 1=1, 2 or 3.
IFAIL=112
On entry, INTER 2=value.
Constraint: INTER 2=1, 2 or 3.
IFAIL=113
On entry, INTER 1=value and INTER 2=value.
On entry at previous call, INTER 1=value, INTER 2=value.
Constraint: if PN≠0, INTER must be unchanged since the last call.
IFAIL=121
On entry, FTYPE=value.
Constraint: FTYPE=1, 2 or 3.
IFAIL=122
On entry, FTYPE=value, On entry at previous call, FTYPE=value.
Constraint: if PN≠0, FTYPE must be unchanged since the previous call.
IFAIL=131
On entry, P=value.
Constraint: absolute value of P must be representable as an integer.
IFAIL=132
On entry, P=value.
Constraint: if FTYPE≠1, P≠0.0. If FTYPE=1, the nearest integer to P must not be 0.
IFAIL=133
On entry, i=value, Z i=value and P=value.
Constraint: if FTYPE=1 or 2 and Z i=0 for any i then P>0.0.
IFAIL=134
On entry, i=value, Z i=value, X i=value and P=value.
Constraint: if FTYPE=3 and Z i=X i for any i then P>0.0.
IFAIL=135
On entry, P=value.
On exit from previous call, P=value.
Constraint: if PN>0 then P must be unchanged since previous call.
IFAIL=151
On entry, PN=value.
Constraint: PN≥0.
IFAIL=152
On entry, PN=value.
On exit from previous call, PN=value.
Constraint: if PN>0 then PN must be unchanged since previous call.
IFAIL=161
RCOMM has been corrupted between calls.
IFAIL=171
On entry, PN=0, LRCOMM=value and M2=value.
Constraint: if PN=0, LRCOMM=0 or LRCOMM≥M2+20.
IFAIL=172
On entry, PN≠0, LRCOMM=value and M2=value.
Constraint: if PN≠0 then LRCOMM≥M2+20.
IFAIL=301
Truncation occurred to avoid overflow, check for extreme values in T, Z, X or for TAU. Results are returned using the truncated values.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

G13MFF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13MFF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

Approximately 4×M2 real elements are internally allocated by G13MFF.
The more data you supply to G13MFF in one call, i.e., the larger NB is, the more efficient the routine will be, particularly if the routine is being run using more than one thread.
Checks are made during the calculation of α and yi to avoid overflow. If a potential overflow is detected the offending value is replaced with a large positive or negative value, as appropriate, and the calculations performed based on the replacement values. In such cases IFAIL=301 is returned. This should not occur in standard usage and will only occur if extreme values of Z, T, X or TAU are supplied.

10 Example

This example reads in three blocks of simulated data from an inhomogeneous time series, then calculates and prints the iterated EMA for m between 2 and 6.

10.1 Program Text

Program Text (g13mffe.f90)

10.2 Program Data

Program Data (g13mffe.d)

10.3 Program Results

Program Results (g13mffe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13MGF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13MGF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13MGF provides a moving average, moving norm, moving variance and moving standard deviation operator for an inhomogeneous time series.

2 Specification

SUBROUTINE G13MGF ( NB, MA, T, TAU, M1, M2, SINIT, INTER, FTYPE, P, PN, WMA, RCOMM, LRCOMM, IFAIL)
INTEGER | NB, M1, M2, INTER(2), FTYPE, PN, LRCOMM, IFAIL
REAL (KIND=nag_wp) | MA(NB), T(NB), TAU, SINIT(*), P, WMA(NB), RCOMM(LRCOMM)

3 Description

G13MGF provides a number of operators for an inhomogeneous time series. The time series is represented by two vectors of length n; a vector of times, t; and a vector of values, z. Each element of the time series is therefore composed of the pair of scalar values ti,zi, for i=1,2,…,n. Time t can be measured in any arbitrary units, as long as all elements of t use the same units.
The main operator available, the moving average (MA), with parameter τ is defined as
MA τ, m 1, m 2; y ti = 1 m 2 - m 1 +1 ∑ j=m 1 m 2 EMA τ~, j; y ti (1)
where τ~= 2⁢τ m 2+m 1 , m 1 and m 2 are user-supplied integers controlling the amount of lag and smoothing respectively, with m 2≥m 1 and EMA(·) is the iterated exponential moving average operator.
The iterated exponential moving average, EMA τ~,m;yti, is defined using the recursive formula:
EMA τ~,m ; y ti = EMA τ~ ; EMA τ~,m-1 ; y ti ti
with
EMA τ~,1;y ti = EMA τ~;y ti
and
EMA τ~ ; y ti = μ ⁢ EMA τ~;y t i-1 + ν-μ ⁢ y i-1 + 1-ν ⁢ yi
where
μ = e-α   and   α = ti - t i-1 τ~ .
The value of ν depends on the method of interpolation chosen and the relationship between y and the input series z depends on the transformation function chosen. G13MGF gives the option of three interpolation methods:
1. | Previous point: | ν=1.
2. | Linear: | ν= 1-μ / α .
3. | Next point: | ν=μ.
and three transformation functions:
1. | Identity: | yi = zi p .
2. | Absolute value: | yi = zi p .
3. | Absolute difference: | yi = zi - MA τ, m 1, m 2; z ti p .
where the notation p is used to denote the integer nearest to p. In addition, if either the absolute value or absolute difference transformation are used then the resulting moving average can be scaled by p-1.
The various parameter options allow a number of different operators to be applied by G13MGF, a few of which are:
(i) Moving Average (MA), as defined in (1) (obtained by setting FTYPE=1 and P=1).
(ii) Moving Norm (MNorm), defined as
MNorm τ,m,p;z = MA τ,1,m; z p 1 / p
(obtained by setting FTYPE=4, M1=1 and M2=m).
(iii) Moving Variance (MVar), defined as
MVar τ,m,p;z = MA τ,1,m; z - MA τ,1,m;z p
(obtained by setting FTYPE=3, M1=1 and M2=m).
(iv) Moving Standard Deviation (MSD), defined as
MSD τ,m,p;z = MA τ,1,m; z - MA τ,1,m;z p 1 / p
(obtained by setting FTYPE=5, M1=1 and M2=m).
For large datasets or where all the data is not available at the same time, z and t can be split into arbitrary sized blocks and G13MGF called multiple times.

4 References

Dacorogna M M, Gencay R, Müller U, Olsen R B and Pictet O V (2001) An Introduction to High-frequency Finance Academic Press
Zumbach G O and Müller U A (2001) Operators on inhomogeneous time series International Journal of Theoretical and Applied Finance 4(1) 147–178

5 Arguments

1:   NB – INTEGERInput
On entry: b, the number of observations in the current block of data. At each call the size of the block of data supplied in MA and T can vary; therefore NB can change between calls to G13MGF.
Constraint: NB≥0.
2:   MA NB – REAL (KIND=nag_wp) arrayInput/Output
On entry: zi, the current block of observations, for i=k+1,…,k+b, where k is the number of observations processed so far, i.e., the value supplied in PN on entry.
On exit: the moving average:
if FTYPE=4 or 5
MA i = MA τ,m 1,m 2;y ti 1/p ,
otherwise
MA i = MA τ,m 1,m 2;y ti .
3:   T NB – REAL (KIND=nag_wp) arrayInput
On entry: ti, the times for the current block of observations, for i=k+1,…,k+b, where k is the number of observations processed so far, i.e., the value supplied in PN on entry.
If ti≤t i-1, IFAIL=31 will be returned, but G13MGF will continue as if t was strictly increasing by using the absolute value. The lagged difference, ti-t i-1 must be sufficiently small that e-α, α=ti-t i-1/τ~ can be calculated without overflowing, for all i.
4:   TAU – REAL (KIND=nag_wp)Input
On entry: τ, the parameter controlling the rate of decay. τ must be sufficiently large that e-α, α=ti-t i-1/τ~ can be calculated without overflowing, for all i, where τ~ = 2⁢τ m 2+m 1 .
Constraint: TAU>0.0.
5:   M1 – INTEGERInput
On entry: m 1, the iteration of the EMA operator at which the sum is started.
Constraint: M1≥1.
6:   M2 – INTEGERInput
On entry: m 2, the iteration of the EMA operator at which the sum is ended.
Constraint: M2≥M1.
7:   SINIT* – REAL (KIND=nag_wp) arrayInput
Note: the dimension of the array SINIT must be at least 2×M2+3 if FTYPE=3 or 5, and at least M2+2 otherwise.
On entry: if PN=0, the values used to start the iterative process, with
  • SINIT 1=t 0,
  • SINIT 2=y 0,
  • SINIT j+2= EMA τ,j ; y t 0 , for i=1,2,…,M2.
In addition, if FTYPE=3 or 5 then
  • SINIT M2+3=z 0,
  • SINIT M2+j+2= EMA τ,j ; z t 0 , for j=1,2,…,M2.
i.e., initial values based on the original data z as opposed to the transformed data y.
If PN≠0, SINIT is not referenced.
Constraint: if FTYPE≠1, SINIT j≥0, for j=2,3,…,M2+2.
8:   INTER 2 – INTEGER arrayInput
On entry: the type of interpolation used with INTER 1 indicating the interpolation method to use when calculating EMA τ,1;z and INTER 2 the interpolation method to use when calculating EMA τ,j;z, j>1.
Three types of interpolation are possible:
INTER i=1
Previous point, with ν=1.
INTER i=2
Linear, with ν=1-μ/α.
INTER i=3
Next point, ν=μ.
Zumbach and Müller (2001) recommend that linear interpolation is used in second and subsequent iterations, i.e., INTER 2=2, irrespective of the interpolation method used at the first iteration, i.e., the value of INTER 1.
Constraint: INTER i=1, 2 or 3, for i=1,2.
9:   FTYPE – INTEGERInput
On entry: the function type used to define the relationship between y and z when calculating EMA τ,1;y. Three functions are provided:
FTYPE=1
The identity function, with yi = zi p .
FTYPE=2 or 4
The absolute value, with yi = zi p .
FTYPE=3 or 5
The absolute difference, with yi = zi - MA τ , m ; y ti p .
If FTYPE=4 or 5 then the resulting vector of averages is scaled by p-1 as described in MA.
Constraint: FTYPE=1, 2, 3, 4 or 5.
10:   P – REAL (KIND=nag_wp)Input/Output
On entry: p, the power used in the transformation function.
On exit: if FTYPE=1, then p, the actual power used in the transformation function is returned, otherwise P is unchanged.
Constraint: P≠0.
11:   PN – INTEGERInput/Output
On entry: k, the number of observations processed so far. On the first call to G13MGF, or when starting to summarise a new dataset, PN must be set to 0. On subsequent calls it must be the same value as returned by the last call to G13MGF.
On exit: k+b, the updated number of observations processed so far.
Constraint: PN≥0.
12:   WMA NB – REAL (KIND=nag_wp) arrayOutput
On exit: either the moving average or exponential moving average, depending on the value of FTYPE.
if FTYPE=3 or 5
WMA i = MA τ ; y ti
otherwise
WMA i = EMA τ~ ; y ti .
13:   RCOMM LRCOMM – REAL (KIND=nag_wp) arrayCommunication Array
On entry: communication array, used to store information between calls to G13MGF. If LRCOMM=0, RCOMM is not referenced, PN must be set to 0 and all the data must be supplied in one go.
14:   LRCOMM – INTEGERInput
On entry: the dimension of the array RCOMM as declared in the (sub)program from which G13MGF is called.
Constraint: LRCOMM=0 or LRCOMM≥2×M2+20.
15:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=11
On entry, NB=value.
Constraint: NB≥0.
IFAIL=31
On entry, i=value, T i-1=value and T i=value.
Constraint: T should be strictly increasing.
IFAIL=32
On entry, i=value, T i-1=value and T i=value.
Constraint: T i≠T i-1 if linear interpolation is being used.
IFAIL=41
On entry, TAU=value.
Constraint: TAU>0.0.
IFAIL=42
On entry, TAU=value.
On entry at previous call, TAU=value.
Constraint: if PN>0 then TAU must be unchanged since previous call.
IFAIL=51
On entry, M1=value.
Constraint: M1≥1.
IFAIL=52
On entry, M1=value.
On entry at previous call, M1=value.
Constraint: if PN>0 then M1 must be unchanged since previous call.
IFAIL=61
On entry, M1=value and M2=value.
Constraint: M2≥M1.
IFAIL=62
On entry, M2=value.
On entry at previous call, M2=value.
Constraint: if PN>0 then M2 must be unchanged since previous call.
IFAIL=71
On entry, FTYPE≠1, j=value and SINIT j=value.
Constraint: if FTYPE≠1, SINIT j≥0.0, for j=2,3,…,M2+2.
IFAIL=81
On entry, INTER 1=value.
Constraint: INTER 1=1, 2 or 3.
IFAIL=82
On entry, INTER 2=value.
Constraint: INTER 2=1, 2 or 3.
IFAIL=83
On entry, INTER 1=value and INTER 2=value.
On entry at previous call, INTER 1=value, INTER 2=value.
Constraint: if PN≠0, INTER must be unchanged since the last call.
IFAIL=91
On entry, FTYPE=value.
Constraint: FTYPE=1, 2, 3, 4 or 5.
IFAIL=92
On entry, FTYPE=value, On entry at previous call, FTYPE=value.
Constraint: if PN≠0, FTYPE must be unchanged since the previous call.
IFAIL=101
On entry, P=value.
Constraint: absolute value of P must be representable as an integer.
IFAIL=102
On entry, P=value.
Constraint: if FTYPE≠1, P≠0.0. If FTYPE=1, the nearest integer to P must not be 0.
IFAIL=103
On entry, i=value, MA i=value and P=value.
Constraint: if FTYPE=1, 2 or 4 and MA i=0 for any i then P>0.0.
IFAIL=104
On entry, i=value, MA i=value, WMA i=value and P=value.
Constraint: if P<0.0, MA i-WMA i≠0.0, for any i.
IFAIL=105
On entry, P=value.
On exit from previous call, P=value.
Constraint: if PN>0 then P must be unchanged since previous call.
IFAIL=111
On entry, PN=value.
Constraint: PN≥0.
IFAIL=112
On entry, PN=value.
On exit from previous call, PN=value.
Constraint: if PN>0 then PN must be unchanged since previous call.
IFAIL=131
RCOMM has been corrupted between calls.
IFAIL=141
On entry, PN=0, LRCOMM=value and M2=value.
Constraint: if PN=0, LRCOMM=0 or LRCOMM≥2⁢M2+20.
IFAIL=142
On entry, PN≠0, LRCOMM=value and M2=value.
Constraint: if PN≠0, LRCOMM≥2⁢M2+20.
IFAIL=301
Truncation occurred to avoid overflow, check for extreme values in T, MA or for TAU. Results are returned using the truncated values.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

G13MGF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
G13MGF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

Approximately 4⁢m 2 real elements are internally allocated by G13MGF. If FTYPE=3 or 5 then a further NB real elements are also allocated.
The more data you supply to G13MGF in one call, i.e., the larger NB is, the more efficient the routine will be, particularly if the routine is being run using more than one thread.
Checks are made during the calculation of α and yi to avoid overflow. If a potential overflow is detected the offending value is replaced with a large positive or negative value, as appropriate, and the calculations performed based on the replacement values. In such cases IFAIL=301 is returned. This should not occur in standard usage and will only occur if extreme values of MA, T or TAU are supplied.

10 Example

The example reads in a simulated time series, t,z and calculates the moving average. The data is supplied in three blocks of differing sizes.

10.1 Program Text

Program Text (g13mgfe.f90)

10.2 Program Data

Program Data (g13mgfe.d)

10.3 Program Results

Program Results (g13mgfe.r)

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13NAF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13NAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13NAF detects change points in a univariate time series, that is, the time points at which some feature of the data, for example the mean, changes. Change points are detected using the PELT (Pruned Exact Linear Time) algorithm using one of a provided set of cost functions.

2 Specification

SUBROUTINE G13NAF ( CTYPE, N, Y, BETA, MINSS, IPARAM, PARAM, NTAU, TAU, SPARAM, IFAIL)
INTEGER | CTYPE, N, MINSS, IPARAM, NTAU, TAU(N), IFAIL
REAL (KIND=nag_wp) | Y(N), BETA, PARAM(1), SPARAM(2*N+2)

3 Description

Let y 1:n=yj:j=1,2,…,n denote a series of data and τ=τi:i=1,2,…,m denote a set of m ordered (strictly monotonic increasing) indices known as change points with 1≤τi≤n and τm=n. For ease of notation we also define τ 0=0. The m change points, τ, split the data into m segments, with the ith segment being of length ni and containing y τ i-1+1:τi.
Given a cost function, C y τ i-1+1:τi G13NAF solves
minimize m,τ ∑ i=1 m C y τ i-1+1:τi + β (1)
where β is a penalty term used to control the number of change points. This minimization is performed using the PELT algorithm of Killick et al. (2012). The PELT algorithm is guaranteed to return the optimal solution to (1) if there exists a constant K such that
C y u+1 : v + C y v+1 : w + K ≤ C y u+1 : w (2)
for all u<v<w.
G13NAF supplies four families of cost function. Each cost function assumes that the series, y, comes from some distribution, D Θ. The parameter space, Θ=θ,ϕ is subdivided into θ containing those parameters allowed to differ in each segment and ϕ those parameters treated as constant across all segments. All four cost functions can then be described in terms of the likelihood function, L and are given by:
C y τ i-1 + 1 : τi = -2 ⁢ log⁡ L θ^i , ϕ | y τ i-1 + 1 : τi
where θ^i is the maximum likelihood estimate of θ within the ith segment. In all four cases setting K=0 satisfies equation (2). Four distributions are available: Normal, Gamma, Exponential and Poisson. Letting
Si= ∑ j=τ i-1 τi yj
the log-likelihoods and cost functions for the four distributions, and the available subdivisions of the parameter space are:
  • Normal distribution: Θ=μ,σ 2
    -2⁢log⁡L = ∑ i=1 m ∑ j=τ i-1 τi log 2⁢π + log σi 2 + yj-μi 2 σi 2
    • Mean changes: θ=μ
      C y τ i-1+1:τi = ∑ j=τ i-1 τi yj - ni-1 ⁢ Si 2 σ 2
    • Variance changes: θ=σ 2
      C y τ i-1+1:τi = ni ⁢ log ∑ j=τ i-1 τi yj-μ 2 - log⁡ni
    • Both mean and variance change: θ=μ,σ 2
      C y τ i-1+1:τi = ni ⁢ log ∑ j=τ i-1 τi yj- ni-1 ⁢ Si 2 - log⁡ni
  • Gamma distribution: Θ=a,b
    -2⁢log⁡L = 2× ∑ i=1 m ∑ j=τ i-1 τi log⁡Γ ai+ ai⁢log⁡bi+ 1-ai⁢log⁡yj+ yj bi
    • Scale changes: θ=b
      C y τ i-1+1:τi = 2⁢ a⁢ ni log⁡Si - log a⁢ ni
  • Exponential Distribution: Θ=λ
    - 2⁢log⁡L = 2× ∑ i=1 m ∑ j=τ i-1 τi log⁡λi+ yj λi
    • Mean changes: θ=λ
      C y τ i-1+1:τi = 2⁢ ni log⁡Si - log⁡ni
  • Poisson distribution: Θ=λ
    -2⁢log⁡L = 2× ∑ i=1 m ∑ j=τ i-1 τi λi- ⌊yj+0.5⌋⁢log⁡λi+ log⁡Γ⌊yj+0.5⌋+1
    • Mean changes: θ=λ
      C y τ i-1+1:τi = 2⁢ Si ⁢ log⁡ni - log⁡Si
      when calculating Si for the Poisson distribution, the sum is calculated for ⌊yi+0.5⌋ rather than yi.

4 References

Chen J and Gupta A K (2010) Parametric Statistical Change Point Analysis With Applications to Genetics Medicine and Finance Second Edition Birkhäuser
Killick R, Fearnhead P and Eckely I A (2012) Optimal detection of changepoints with a linear computational cost Journal of the American Statistical Association 107:500 1590–1598

5 Arguments

1:   CTYPE – INTEGERInput
On entry: a flag indicating the assumed distribution of the data and the type of change point being looked for.
CTYPE=1
Data from a Normal distribution, looking for changes in the mean, μ.
CTYPE=2
Data from a Normal distribution, looking for changes in the standard deviation σ.
CTYPE=3
Data from a Normal distribution, looking for changes in the mean, μ and standard deviation σ.
CTYPE=4
Data from a Gamma distribution, looking for changes in the scale parameter b.
CTYPE=5
Data from an exponential distribution, looking for changes in λ.
CTYPE=6
Data from a Poisson distribution, looking for changes in λ.
Constraint: CTYPE=1, 2, 3, 4, 5 or 6.
2:   N – INTEGERInput
On entry: n, the length of the time series.
Constraint: N≥2.
3:   Y N – REAL (KIND=nag_wp) arrayInput
On entry: y, the time series.
if CTYPE=6, that is the data is assumed to come from a Poisson distribution, ⌊y+0.5⌋ is used in all calculations.
Constraints:
  • if CTYPE=4, 5 or 6, Y i≥0, for i=1,2,…,N;
  • if CTYPE=6, each value of Y must be representable as an integer;
  • if CTYPE≠6, each value of Y must be small enough such that Y i 2, for i=1,2,…,N, can be calculated without incurring overflow.
4:   BETA – REAL (KIND=nag_wp)Input
On entry: β, the penalty term.
There are a number of standard ways of setting β, including:
SIC or BIC
β=p×log n
AIC
β=2⁢p
Hannan-Quinn
β=2⁢p×log log n
where p is the number of parameters being treated as estimated in each segment. This is usually set to 2 when CTYPE=3 and 1 otherwise.
If no penalty is required then set β=0. Generally, the smaller the value of β the larger the number of suggested change points.
5:   MINSS – INTEGERInput
On entry: the minimum distance between two change points, that is τi-τ i-1≥MINSS.
Constraint: MINSS≥2.
6:   IPARAM – INTEGERInput
On entry: if IPARAM=1 distributional parameters have been supplied in PARAM.
Constraints:
  • if CTYPE=4, IPARAM=1;
  • otherwise IPARAM=0 or 1.
7:   PARAM 1 – REAL (KIND=nag_wp) arrayInput
On entry: ϕ, values for the parameters that will be treated as fixed. If IPARAM=0 then PARAM is not referenced.
If CTYPE=1
  • if IPARAM=0, σ, the standard deviation of the Normal distribution, is estimated from the full input data. Otherwise σ=PARAM 1.
If CTYPE=2
  • If IPARAM=0, μ, the mean of the Normal distribution, is estimated from the full input data. Otherwise μ=PARAM 1.
If CTYPE=4, PARAM 1 must hold the shape, a, for the Gamma distribution, otherwise PARAM is not referenced.
Constraint: if CTYPE=1 or 4, PARAM 1>0.0.
8:   NTAU – INTEGEROutput
On exit: m, the number of change points detected.
9:   TAU N – INTEGER arrayOutput
On exit: the first m elements of TAU hold the location of the change points. The ith segment is defined by y τ i-1+1 to y τi, where τ 0=0 and τi=TAU i,1≤i≤m.
The remainder of TAU is used as workspace.
10:   SPARAM 2×N+2 – REAL (KIND=nag_wp) arrayOutput
On exit: the estimated values of the distribution parameters in each segment
CTYPE=1, 2 or 3
SPARAM 2⁢i-1=μi and SPARAM 2⁢i=σi for i=1,2,…,m, where μi and σi is the mean and standard deviation, respectively, of the values of y in the ith segment.
It should be noted that σi=σj when CTYPE=1 and μi=μj when CTYPE=2, for all i and j.
CTYPE=4
SPARAM 2⁢i-1=ai and SPARAM 2⁢i=bi for i=1,2,…,m, where ai and bi are the shape and scale parameters, respectively, for the values of y in the ith segment. It should be noted that ai=PARAM 1 for all i.
CTYPE=5 or 6
SPARAM i=λi for i=1,2,…,m, where λi is the mean of the values of y in the ith segment.
The remainder of SPARAM is used as workspace.
11:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=11
On entry, CTYPE=value.
Constraint: CTYPE=1, 2, 3, 4, 5 or 6.
IFAIL=21
On entry, N=value.
Constraint: N≥2.
IFAIL=31
On entry, CTYPE=value and Y value=value.
Constraint: if CTYPE=4, 5 or 6 then Y i≥0.0, for i=1,2,…,N.
IFAIL=32
On entry, Y value=value, is too large.
IFAIL=51
On entry, MINSS=value.
Constraint: MINSS≥2.
IFAIL=61
On entry, IPARAM=value.
Constraint: if CTYPE≠4 then IPARAM=0 or 1.
IFAIL=62
On entry, IPARAM=value.
Constraint: if CTYPE=4 then IPARAM=1.
IFAIL=71
On entry, CTYPE=value and PARAM 1=value.
Constraint: if CTYPE=1 or 4 and IPARAM=1, then PARAM 1>0.0.
IFAIL=200
To avoid overflow some truncation occurred when calculating the cost function, C. All output is returned as normal.
IFAIL=201
To avoid overflow some truncation occurred when calculating the parameter estimates returned in SPARAM. All output is returned as normal.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

For efficiency reasons, when calculating the cost functions, C and the parameter estimates returned in SPARAM, this routine makes use of the mathematical identities:
∑ j=u v yj 2 = ∑ j=1 v yj 2 - ∑ j=1 u-1 yj 2
and
∑ j=1 n yj-y- 2 = ∑ j=1 n yj 2 - n ⁢ y- 2
where y-=n-1∑j=1 n yj.
The input data, y, is scaled in order to try and mitigate some of the known instabilities associated with using these formulations. The results returned by G13NAF should be sufficient for the majority of datasets. If a more stable method of calculating C is deemed necessary, G13NBF can be used and the method chosen implemented in the user-supplied cost function.

8 Parallelism and Performance

G13NAF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example identifies changes in the mean, under the assumption that the data is normally distributed, for a simulated dataset with 100 observations. A BIC penalty is used, that is β=log⁡n≈4.6, the minimum segment size is set to 2 and the variance is fixed at 1 across the whole input series.

10.1 Program Text

Program Text (g13nafe.f90)

10.2 Program Data

Program Data (g13nafe.d)

10.3 Program Results

Program Results (g13nafe.r)

This example plot shows the original data series, the estimated change points and the estimated mean in each of the identified segments.
GnuplotProduced by GNUPLOT 4.6 patchlevel 3 −3 −2 −1 0 1 2 3 4 0 10 20 30 40 50 60 70 80 90 100 Value Time Example Program Simulated time series and the corresponding changes in mean gnuplot_plot_1
G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13NBF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13NBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13NBF detects change points in a univariate time series, that is, the time points at which some feature of the data, for example the mean, changes. Change points are detected using the PELT (Pruned Exact Linear Time) algorithm and a user-supplied cost function.

2 Specification

SUBROUTINE G13NBF ( N, BETA, MINSS, K, COSTFN, NTAU, TAU, Y, IUSER, RUSER, IFAIL)
INTEGER | N, MINSS, NTAU, TAU(N), IUSER(*), IFAIL
REAL (KIND=nag_wp) | BETA, K, Y(*), RUSER(*)
EXTERNAL | COSTFN

3 Description

Let y 1:n=yj:j=1,2,…,n denote a series of data and τ=τi:i=1,2,…,m denote a set of m ordered (strictly monotonic increasing) indices known as change points with 1≤τi≤n and τm=n. For ease of notation we also define τ 0=0. The m change points, τ, split the data into m segments, with the ith segment being of length ni and containing y τ i-1+1:τi.
Given a user-supplied cost function, C y τ i-1+1:τi G13NBF solves
minimize m,τ ∑ i=1 m C y τ i-1+1:τi + β (1)
where β is a penalty term used to control the number of change points. This minimization is performed using the PELT algorithm of Killick et al. (2012). The PELT algorithm is guaranteed to return the optimal solution to (1) if there exists a constant K such that
C y u+1 : v + C y v+1 : w + K ≤ C y u+1 : w (2)
for all u<v<w

4 References

Chen J and Gupta A K (2010) Parametric Statistical Change Point Analysis With Applications to Genetics Medicine and Finance Second Edition Birkhäuser
Killick R, Fearnhead P and Eckely I A (2012) Optimal detection of changepoints with a linear computational cost Journal of the American Statistical Association 107:500 1590–1598

5 Arguments

1:   N – INTEGERInput
On entry: n, the length of the time series.
Constraint: N≥2.
2:   BETA – REAL (KIND=nag_wp)Input
On entry: β, the penalty term.
There are a number of standard ways of setting β, including:
SIC or BIC
β=p×log n
AIC
β=2⁢p
Hannan-Quinn
β=2⁢p×log log n
where p is the number of parameters being treated as estimated in each segment. The value of p will depend on the cost function being used.
If no penalty is required then set β=0. Generally, the smaller the value of β the larger the number of suggested change points.
3:   MINSS – INTEGERInput
On entry: the minimum distance between two change points, that is τi-τ i-1≥MINSS.
Constraint: MINSS≥2.
4:   K – REAL (KIND=nag_wp)Input
On entry: K, the constant value that satisfies equation (2). If K exists, it is unlikely to be unique in such cases, it is recommened that the largest value of K, that satisfies equation (2), is chosen. No check is made that K is the correct value for the supplied cost function.
5:   COSTFN – SUBROUTINE, supplied by the user.External Procedure
The cost function, C. COSTFN must calculate a vector of costs for a number of segments.
The specification of COSTFN is:
SUBROUTINE COSTFN ( TS, NR, R, C, Y, IUSER, RUSER, INFO)
INTEGER | TS, NR, R(NR), IUSER(*), INFO
REAL (KIND=nag_wp) | C(NR), Y(*), RUSER(*)
1:   TS – INTEGERInput
On entry: a reference time point.
2:   NR – INTEGERInput
On entry: number of segments being considered.
3:   R NR – INTEGER arrayInput
On entry: time points which, along with TS, define the segments being considered, 0≤R i≤n for i=1,2,…NR.
4:   C NR – REAL (KIND=nag_wp) arrayOutput
On exit: the cost function, C, with
C i= C y ri:t ​ if ​t>ri, C y t:ri ​ otherwise.
where t=TS and ri=R i.
It should be noted that if t>ri for any value of i then it will be true for all values of i. Therefore the inequality need only be tested once per call to COSTFN.
5:   Y* – REAL (KIND=nag_wp) arrayUser Data
COSTFN is called with Y as supplied to G13NBF. You are free to use the array Y to supply information to COSTFN.
Y is supplied in addition to IUSER and RUSER for ease of coding as in most cases COSTFN will require (functions of) the time series, y.
6:   IUSER* – INTEGER arrayUser Workspace
7:   RUSER* – REAL (KIND=nag_wp) arrayUser Workspace
COSTFN is called with the arguments IUSER and RUSER as supplied to G13NBF. You are free to use the arrays IUSER and RUSER to supply information to COSTFN as an alternative to using COMMON global variables.
8:   INFO – INTEGERInput/Output
On entry: INFO=0.
On exit: set INFO to a nonzero value if you wish G13NBF to terminate with IFAIL=51.
COSTFN must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which G13NBF is called. Arguments denoted as Input must not be changed by this procedure.
6:   NTAU – INTEGEROutput
On exit: m, the number of change points detected.
7:   TAU N – INTEGER arrayOutput
On exit: the first m elements of TAU hold the location of the change points. The ith segment is defined by y τ i-1+1 to y τi, where τ 0=0 and τi=TAU i,1≤i≤m.
The remainder of TAU is used as workspace.
8:   Y* – REAL (KIND=nag_wp) arrayUser Data
Y is not used by G13NBF, but is passed directly to COSTFN and may be used to pass information to this routine. Y will usually be used to pass (functions of) the time series, y of interest.
9:   IUSER* – INTEGER arrayUser Workspace
10:   RUSER* – REAL (KIND=nag_wp) arrayUser Workspace
IUSER and RUSER are not used by G13NBF, but are passed directly to COSTFN and may be used to pass information to this routine as an alternative to using COMMON global variables.
11:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=11
On entry, N=value.
Constraint: N≥2.
IFAIL=31
On entry, MINSS=value.
Constraint: MINSS≥2.
IFAIL=51
User requested termination.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

G13NBF is not threaded in any implementation.

9 Further Comments

G13NAF performs the same calculations for a cost function selected from a provided set of cost functions. If the required cost function belongs to this provided set then G13NAF can be used without the need to provide a cost function routine.

10 Example

This example identifies changes in the scale parameter, under the assumption that the data has a gamma distribution, for a simulated dataset with 100 observations. A penalty, β of 3.6 is used and the minimum segment size is set to 3. The shape parameter is fixed at 2.1 across the whole input series.
The cost function used is
C y τ i-1+1:τi = 2⁢ a⁢ ni log⁡Si - log a⁢ ni
where a is a shape parameter that is fixed for all segments and ni=τi-τ i-1+1.

10.1 Program Text

Program Text (g13nbfe.f90)

10.2 Program Data

Program Data (g13nbfe.d)

10.3 Program Results

Program Results (g13nbfe.r)

This example plot shows the original data series and the estimated change points.
GnuplotProduced by GNUPLOT 4.6 patchlevel 3 0 0.5 1 1.5 2 2.5 3 3.5 4 0 10 20 30 40 50 60 70 80 90 100 Value Time Example Program Simulated time series and the corresponding changes in scale b, assuming y = Ga(2.1,b) gnuplot_plot_1
G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13NDF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13NDF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13NDF detects change points in a univariate time series, that is, the time points at which some feature of the data, for example the mean, changes. Change points are detected using binary segmentation using one of a provided set of cost functions.

2 Specification

SUBROUTINE G13NDF ( CTYPE, N, Y, BETA, MINSS, IPARAM, PARAM, MDEPTH, NTAU, TAU, SPARAM, IFAIL)
INTEGER | CTYPE, N, MINSS, IPARAM, MDEPTH, NTAU, TAU(*), IFAIL
REAL (KIND=nag_wp) | Y(N), BETA, PARAM(1), SPARAM(2*N)

3 Description

Let y 1:n=yj:j=1,2,…,n denote a series of data and τ=τi:i=1,2,…,m denote a set of m ordered (strictly monotonic increasing) indices known as change points, with 1≤τi≤n and τm=n. For ease of notation we also define τ 0=0. The m change points, τ, split the data into m segments, with the ith segment being of length ni and containing y τ i-1+1:τi.
Given a cost function, C y τ i-1+1:τi, G13NDF gives an approximate solution to
minimize m,τ ∑ i=1 m C y τ i-1+1:τi + β
where β is a penalty term used to control the number of change points. The solution is obtained in an iterative manner as follows:
1. | Set u=1, w=n and k=0
2. | Set k=k+1. If k>K, where K is a user-supplied control parameter, then terminate the process for this segment.
3. Find v that minimizes
C y u:v + C y v+1:w
4. Test
C y u:v + C y v+1:w + β < C y u:w (1)
5. | If inequality (1) is false then the process is terminated for this segment.
6. | If inequality (1) is true, then v is added to the set of change points, and the segment is split into two subsegments, y u:v and y v+1:w. The whole process is repeated from step 2 independently on each subsegment, with the relevant changes to the definition of u and w (i.e., w is set to v when processing the left hand subsegment and u is set to v+1 when processing the right hand subsegment.
The change points are ordered to give τ.
G13NDF supplies four families of cost function. Each cost function assumes that the series, y, comes from some distribution, D Θ. The parameter space, Θ=θ,ϕ is subdivided into θ containing those parameters allowed to differ in each segment and ϕ those parameters treated as constant across all segments. All four cost functions can then be described in terms of the likelihood function, L and are given by:
C y τ i-1 + 1 : τi = -2 ⁢ log⁡ L θ^i , ϕ | y τ i-1 + 1 : τi
where the θ^i is the maximum likelihood estimate of θ within the ith segment. Four distributions are available; Normal, Gamma, Exponential and Poisson distributions. Letting
Si= ∑ j=τ i-1 τi yj
the log-likelihoods and cost functions for the four distributions, and the available subdivisions of the parameter space are:
  • Normal distribution: Θ=μ,σ 2
    -2⁢log⁡L = ∑ i=1 m ∑ j=τ i-1 τi log 2⁢π + log σi 2 + yj-μi 2 σi 2
    • Mean changes: θ=μ
      C y τ i-1+1:τi = ∑ j=τ i-1 τi yj - ni-1 ⁢ Si 2 σ 2
    • Variance changes: θ=σ 2
      C y τ i-1+1:τi = ni ⁢ log ∑ j=τ i-1 τi yj-μ 2 - log⁡ni
    • Both mean and variance change: θ=μ,σ 2
      C y τ i-1+1:τi = ni ⁢ log ∑ j=τ i-1 τi yj- ni-1 ⁢ Si 2 - log⁡ni
  • Gamma distribution: Θ=a,b
    -2⁢log⁡L = 2× ∑ i=1 m ∑ j=τ i-1 τi log⁡Γ ai+ ai⁢log⁡bi+ 1-ai⁢log⁡yj+ yj bi
    • Scale changes: θ=b
      C y τ i-1+1:τi = 2⁢ a⁢ ni log⁡Si - log a⁢ ni
  • Exponential Distribution: Θ=λ
    - 2⁢log⁡L = 2× ∑ i=1 m ∑ j=τ i-1 τi log⁡λi+ yj λi
    • Mean changes: θ=λ
      C y τ i-1+1:τi = 2⁢ ni log⁡Si - log⁡ni
  • Poisson distribution: Θ=λ
    -2⁢log⁡L = 2× ∑ i=1 m ∑ j=τ i-1 τi λi- ⌊yj+0.5⌋⁢log⁡λi+ log⁡Γ⌊yj+0.5⌋+1
    • Mean changes: θ=λ
      C y τ i-1+1:τi = 2⁢ Si ⁢ log⁡ni - log⁡Si
      when calculating Si for the Poisson distribution, the sum is calculated for ⌊yi+0.5⌋ rather than yi.

4 References

Chen J and Gupta A K (2010) Parametric Statistical Change Point Analysis With Applications to Genetics Medicine and Finance Second Edition Birkhäuser
West D H D (1979) Updating mean and variance estimates: An improved method Comm. ACM 22 532–555

5 Arguments

1:   CTYPE – INTEGERInput
On entry: a flag indicating the assumed distribution of the data and the type of change point being looked for.
CTYPE=1
Data from a Normal distribution, looking for changes in the mean, μ.
CTYPE=2
Data from a Normal distribution, looking for changes in the standard deviation σ.
CTYPE=3
Data from a Normal distribution, looking for changes in the mean, μ and standard deviation σ.
CTYPE=4
Data from a Gamma distribution, looking for changes in the scale parameter b.
CTYPE=5
Data from an exponential distribution, looking for changes in λ.
CTYPE=6
Data from a Poisson distribution, looking for changes in λ.
Constraint: CTYPE=1, 2, 3, 4, 5 or 6.
2:   N – INTEGERInput
On entry: n, the length of the time series.
Constraint: N≥2.
3:   Y N – REAL (KIND=nag_wp) arrayInput
On entry: y, the time series.
if CTYPE=6, that is the data is assumed to come from a Poisson distribution, ⌊y+0.5⌋ is used in all calculations.
Constraints:
  • if CTYPE=4, 5 or 6, Y i≥0, for i=1,2,…,N;
  • if CTYPE=6, each value of Y must be representable as an integer;
  • if CTYPE≠6, each value of Y must be small enough such that Y i 2, for i=1,2,…,N, can be calculated without incurring overflow.
4:   BETA – REAL (KIND=nag_wp)Input
On entry: β, the penalty term.
There are a number of standard ways of setting β, including:
SIC or BIC
β=p×log n
AIC
β=2⁢p
Hannan-Quinn
β=2⁢p×log log n
where p is the number of parameters being treated as estimated in each segment. This is usually set to 2 when CTYPE=3 and 1 otherwise.
If no penalty is required then set β=0. Generally, the smaller the value of β the larger the number of suggested change points.
5:   MINSS – INTEGERInput
On entry: the minimum distance between two change points, that is τi-τ i-1≥MINSS.
Constraint: MINSS≥2.
6:   IPARAM – INTEGERInput
On entry: if IPARAM=1 distributional parameters have been supplied in PARAM.
Constraints:
  • if CTYPE=4, IPARAM=1;
  • otherwise IPARAM=0 or 1.
7:   PARAM 1 – REAL (KIND=nag_wp) arrayInput
On entry: ϕ, values for the parameters that will be treated as fixed. If IPARAM=0 then PARAM is not referenced.
If CTYPE=1
  • if IPARAM=0, σ, the standard deviation of the Normal distribution, is estimated from the full input data. Otherwise σ=PARAM 1.
If CTYPE=2
  • If IPARAM=0, μ, the mean of the Normal distribution, is estimated from the full input data. Otherwise μ=PARAM 1.
If CTYPE=4, PARAM 1 must hold the shape, a, for the Gamma distribution, otherwise PARAM is not referenced.
Constraint: if CTYPE=1 or 4, PARAM 1>0.0.
8:   MDEPTH – INTEGERInput
On entry: K, the maximum depth for the iterative process, which in turn puts an upper limit on the number of change points with m≤2 K.
If K≤0 then no limit is put on the depth of the iterative process and no upper limit is put on the number of change points, other than that inherent in the length of the series and the value of MINSS.
9:   NTAU – INTEGEROutput
On exit: m, the number of change points detected.
10:   TAU* – INTEGER arrayOutput
Note: the dimension of the array TAU must be at least min⌈NMINSS⌉,2 MDEPTH if MDEPTH>0, and at least ⌈NMINSS⌉ otherwise.
On exit: the first m elements of TAU hold the location of the change points. The ith segment is defined by y τ i-1+1 to y τi, where τ 0=0 and τi=TAU i,1≤i≤m.
The remainder of TAU is used as workspace.
11:   SPARAM 2×N – REAL (KIND=nag_wp) arrayOutput
On exit: the estimated values of the distribution parameters in each segment
CTYPE=1, 2 or 3
SPARAM 2⁢i-1=μi and SPARAM 2⁢i=σi for i=1,2,…,m, where μi and σi is the mean and standard deviation, respectively, of the values of y in the ith segment.
It should be noted that σi=σj when CTYPE=1 and μi=μj when CTYPE=2, for all i and j.
CTYPE=4
SPARAM 2⁢i-1=ai and SPARAM 2⁢i=bi for i=1,2,…,m, where ai and bi are the shape and scale parameters, respectively, for the values of y in the ith segment. It should be noted that ai=PARAM 1 for all i.
CTYPE=5 or 6
SPARAM i=λi for i=1,2,…,m, where λi is the mean of the values of y in the ith segment.
The remainder of SPARAM is used as workspace.
12:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=11
On entry, CTYPE=value.
Constraint: CTYPE=1, 2, 3, 4, 5 or 6.
IFAIL=21
On entry, N=value.
Constraint: N≥2.
IFAIL=31
On entry, CTYPE=value and Y value=value.
Constraint: if CTYPE=4, 5 or 6 then Y i≥0.0, for i=1,2,…,N.
IFAIL=32
On entry, Y value=value, is too large.
IFAIL=51
On entry, MINSS=value.
Constraint: MINSS≥2.
IFAIL=61
On entry, IPARAM=value.
Constraint: if CTYPE≠4 then IPARAM=0 or 1.
IFAIL=62
On entry, IPARAM=value.
Constraint: if CTYPE=4 then IPARAM=1.
IFAIL=71
On entry, CTYPE=value and PARAM 1=value.
Constraint: if CTYPE=1 or 4 and IPARAM=1, then PARAM 1>0.0.
IFAIL=200
To avoid overflow some truncation occurred when calculating the cost function, C. All output is returned as normal.
IFAIL=201
To avoid overflow some truncation occurred when calculating the parameter estimates returned in SPARAM. All output is returned as normal.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The calculation of means and sums of squares about the mean during the evaluation of the cost functions are based on the one pass algorithm of West (1979) and are believed to be stable.

8 Parallelism and Performance

G13NDF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

None.

10 Example

This example identifies changes in the mean, under the assumption that the data is normally distributed, for a simulated dataset with 100 observations. A BIC penalty is used, that is β=log⁡n≈4.6, the minimum segment size is set to 2 and the variance is fixed at 1 across the whole input series.

10.1 Program Text

Program Text (g13ndfe.f90)

10.2 Program Data

Program Data (g13ndfe.d)

10.3 Program Results

Program Results (g13ndfe.r)

This example plot shows the original data series, the estimated change points and the estimated mean in each of the identified segments.
GnuplotProduced by GNUPLOT 4.6 patchlevel 3 −3 −2 −1 0 1 2 3 4 0 10 20 30 40 50 60 70 80 90 100 Value Time Example Program Simulated time series and the corresponding changes in mean gnuplot_plot_1
G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


G13NEF : NAG Library, Mark 26

G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

G13NEF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

G13NEF detects change points in a univariate time series, that is, the time points at which some feature of the data, for example the mean, changes. Change points are detected using binary segmentation for a user-supplied cost function.

2 Specification

SUBROUTINE G13NEF ( N, BETA, MINSS, MDEPTH, CHGPFN, NTAU, TAU, Y, IUSER, RUSER, IFAIL)
INTEGER | N, MINSS, MDEPTH, NTAU, TAU(*), IUSER(*), IFAIL
REAL (KIND=nag_wp) | BETA, Y(*), RUSER(*)
EXTERNAL | CHGPFN

3 Description

Let y 1:n=yj:j=1,2,…,n denote a series of data and τ=τi:i=1,2,…,m denote a set of m ordered (strictly monotonic increasing) indices known as change points with 1≤τi≤n and τm=n. For ease of notation we also define τ 0=0. The m change points, τ, split the data into m segments, with the ith segment being of length ni and containing y τ i-1+1:τi.
Given a cost function, C y τ i-1+1:τi, G13NEF gives an approximate solution to
minimize m,τ ∑ i=1 m C y τ i-1+1:τi + β
where β is a penalty term used to control the number of change points. The solution is obtained in an iterative manner as follows:
1. | Set u=1, w=n and k=0
2. | Set k=k+1. If k>K, where K is a user-supplied control parameter, then terminate the process for this segment.
3. Find v that minimizes
C y u:v + C y v+1:w
4. Test
C y u:v + C y v+1:w + β < C y u:w (1)
5. | If inequality (1) is false then the process is terminated for this segment.
6. | If inequality (1) is true, then v is added to the set of change points, and the segment is split into two subsegments, y u:v and y v+1:w. The whole process is repeated from step 2 independently on each subsegment, with the relevant changes to the definition of u and w (i.e., w is set to v when processing the left hand subsegment and u is set to v+1 when processing the right hand subsegment.
The change points are ordered to give τ.

4 References

Chen J and Gupta A K (2010) Parametric Statistical Change Point Analysis With Applications to Genetics Medicine and Finance Second Edition Birkhäuser

5 Arguments

1:   N – INTEGERInput
On entry: n, the length of the time series.
Constraint: N≥2.
2:   BETA – REAL (KIND=nag_wp)Input
On entry: β, the penalty term.
There are a number of standard ways of setting β, including:
SIC or BIC
β=p×log n.
AIC
β=2⁢p.
Hannan-Quinn
β=2⁢p×log log n.
where p is the number of parameters being treated as estimated in each segment. The value of p will depend on the cost function being used.
If no penalty is required then set β=0. Generally, the smaller the value of β the larger the number of suggested change points.
3:   MINSS – INTEGERInput
On entry: the minimum distance between two change points, that is τi-τ i-1≥MINSS.
Constraint: MINSS≥2.
4:   MDEPTH – INTEGERInput
On entry: K, the maximum depth for the iterative process, which in turn puts an upper limit on the number of change points with m≤2 K.
If K≤0 then no limit is put on the depth of the iterative process and no upper limit is put on the number of change points, other than that inherent in the length of the series and the value of MINSS.
5:   CHGPFN – SUBROUTINE, supplied by the user.External Procedure
CHGPFN must calculate a proposed change point, and the associated costs, within a specified segment.
The specification of CHGPFN is:
SUBROUTINE CHGPFN ( SIDE, U, W, MINSS, V, COST, Y, IUSER, RUSER, INFO)
INTEGER | SIDE, U, W, MINSS, V, IUSER(*), INFO
REAL (KIND=nag_wp) | COST(3), Y(*), RUSER(*)
1:   SIDE – INTEGERInput
On entry: flag indicating what CHGPFN must calculate and at which point of the Binary Segmentation it has been called.
SIDE=-1
only C y u:w need be calculated and returned in COST 1, neither V nor the other elements of COST need be set. In this case, u=1 and w=n.
SIDE=0
all elements of COST and V must be set. In this case, u=1 and w=n.
SIDE=1
the segment, y u:w, is a left hand side subsegment from a previous iteration of the Binary Segmentation algorithm. All elements of COST and V must be set.
SIDE=2
the segment, y u:w, is a right hand side subsegment from a previous iteration of the Binary Segmentation algorithm. All elements of COST and V must be set.
The distinction between SIDE=1 and 2 may allow for CHGPFN to be implemented in a more efficient manner. See section Section 10 for one such example.
The first call to CHGPFN will always have SIDE=-1 and the second call will always have SIDE=0. All subsequent calls will be made with SIDE=1 or 2.
2:   U – INTEGERInput
On entry: u, the start of the segment of interest.
3:   W – INTEGERInput
On entry: w, the end of the segment of interest.
4:   MINSS – INTEGERInput
On entry: the minimum distance between two change points, as passed to G13NEF.
5:   V – INTEGEROutput
On exit: if SIDE=-1 then V need not be set.
if SIDE≠-1 then v, the proposed change point. That is, the value which minimizes
minimize v C y u:v + C y v+1:w
for v=u+MINSS-1 to w-MINSS.
6:   COST 3 – REAL (KIND=nag_wp) arrayOutput
On exit: costs associated with the proposed change point, v.
If SIDE=-1 then COST 1=C y u:w and the remaining two elements of COST need not be set.
If SIDE≠-1 then
  • COST 1= C y u:v + C y v+1:w .
  • COST 2= C y u:v .
  • COST 3= C y v+1:w .
7:   Y* – REAL (KIND=nag_wp) arrayUser Data
CHGPFN is called with Y as supplied to G13NEF. You are free to use the array Y to supply information to CHGPFN.
Y is supplied in addition to IUSER and RUSER for ease of coding as in most cases CHGPFN will require (functions of) the time series, y.
8:   IUSER* – INTEGER arrayUser Workspace
9:   RUSER* – REAL (KIND=nag_wp) arrayUser Workspace
CHGPFN is called with the arguments IUSER and RUSER as supplied to G13NEF. You are free to use the arrays IUSER and RUSER to supply information to CHGPFN as an alternative to using COMMON global variables.
10:   INFO – INTEGERInput/Output
On entry: INFO=0.
On exit: in most circumstances INFO should remain unchanged.
If INFO is set to a strictly positive value then G13NEF terminates with IFAIL=51.
If INFO is set to a strictly negative value the current segment is skipped (i.e., no change points are considered in this segment) and G13NEF continues as normal. If INFO was set to a strictly negative value at any point and no other errors occur then G13NEF will terminate with IFAIL=52.
CHGPFN must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which G13NEF is called. Arguments denoted as Input must not be changed by this procedure.
6:   NTAU – INTEGEROutput
On exit: m, the number of change points detected.
7:   TAU* – INTEGER arrayOutput
Note: the dimension of the array TAU must be at least min⌈NMINSS⌉,2 MDEPTH if MDEPTH>0, and at least ⌈NMINSS⌉ otherwise.
On exit: the first m elements of TAU hold the location of the change points. The ith segment is defined by y τ i-1+1 to y τi, where τ 0=0 and τi=TAU i,1≤i≤m.
The remainder of TAU is used as workspace.
8:   Y* – REAL (KIND=nag_wp) arrayUser Data
Y is not used by G13NEF, but is passed directly to CHGPFN and may be used to pass information to this routine. Y will usually be used to pass (functions of) the time series, y of interest.
9:   IUSER* – INTEGER arrayUser Workspace
10:   RUSER* – REAL (KIND=nag_wp) arrayUser Workspace
IUSER and RUSER are not used by G13NEF, but are passed directly to CHGPFN and may be used to pass information to this routine as an alternative to using COMMON global variables.
11:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=11
On entry, N=value.
Constraint: N≥2.
IFAIL=31
On entry, MINSS=value.
Constraint: MINSS≥2.
IFAIL=51
User requested termination by setting INFO=value.
IFAIL=52
User requested a segment to be skipped by setting INFO=value.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

G13NEF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

G13NDF performs the same calculations for a cost function selected from a provided set of cost functions. If the required cost function belongs to this provided set then G13NDF can be used without the need to provide a cost function routine.

10 Example

This example identifies changes in the scale parameter, under the assumption that the data has a gamma distribution, for a simulated dataset with 100 observations. A penalty, β of 3.6 is used and the minimum segment size is set to 3. The shape parameter is fixed at 2.1 across the whole input series.
The cost function used is
C y τ i-1+1:τi = 2⁢ a⁢ ni log⁡Si - log a⁢ ni
where a is a shape parameter that is fixed for all segments and ni=τi-τ i-1+1.

10.1 Program Text

Program Text (g13nefe.f90)

10.2 Program Data

Program Data (g13nefe.d)

10.3 Program Results

Program Results (g13nefe.r)

This example plot shows the original data series and the estimated change points.
GnuplotProduced by GNUPLOT 4.6 patchlevel 3 0 0.5 1 1.5 2 2.5 3 3.5 4 0 10 20 30 40 50 60 70 80 90 100 Value Time Example Program Simulated time series and the corresponding changes in scale b, assuming y = Ga(2.1,b) gnuplot_plot_1
G13 Chapter Contents
G13 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


Code Contributors : NAG Library, Mark 26

NAG Library

Code Contributors

Below we list the names of those people who have made a substantial contribution to the design, development and validation of software of the Library (in the designated chapters).
The list includes the names of those who have collaborated with NAG specifically to develop software for the Library; and also the names of the authors of public-domain software that has been adapted for inclusion in the Library. It gives the institutions at which the individuals were working at the time they made their contributions, not necessarily their present addresses. It does not include the names of those – too numerous to mention individually – who have contributed ideas, criticisms, reports of errors, or suggestions for improvements to the software; nor does it cover work done by NAG full-time staff or those who are responsible for implementing the Library on different machines.
The routines in Chapter D06 (Mesh Generation) have been derived from material in the MODULEF package from INRIA (Institut National de Recherche en Informatique et Automatique). NAG is grateful to INRIA for their agreement to develop this material.
The LAPACK project is the source of all routines in Chapters F07 and F08; we acknowledge by name the original contributors to the project but also recognize that many other people have been involved in updating and adding to the Lapack project. We would therefore like to acknowledge the efforts of the wider LAPACK community for their contributions to Chapters F07 and F08.
Some routines in Chapters E04 and F02 use an implementation of HSL_MA97 from HSL, a collection of Fortran codes for large-scale scientific computation (see http://www.hsl.rl.ac.uk).
We acknowledge with gratitude the contributions of all these people to the development of the Library.
J P Abbott, University of Nottingham | (Chapters F03 and F04)
D Amos, Sandia National Laboratories, Albuquerque | (Chapter S)
E Anderson, University of Tennessee and Cray Research | (Chapters F07 and F08)
G T Anthony, National Physical Laboratory | (Chapters E01 and E02)
Z Bai, New York University, University of Tennessee and University of Kentucky | (Chapters F07 and F08)
A Bain, BNP Paribas | (Chapter S)
H M Barber, National Physical Laboratory | (Chapter E04)
I Barrodale, University of Victoria | (Chapter E02)
D A Barry, University of Western Australia | (Chapter C05)
S J Barry, Griffith University | (Chapter C05)
R H Bartels, Johns Hopkins University | (Chapter E02)
W Barth, Technische Hochschule Darmstadt | (Chapter F02)
M Berzins, University of Leeds | (Chapters D02 and D03)
G P Bhattacharjee, Indian Institute of Technology, Kharagpur | (Chapter G01)
C Bischof, Argonne National Laboratory | (Chapters F07 and F08)
R Borsdorf, University of Manchester | (Chapter G02)
J M Boyle, Argonne National Laboratory | (Chapter F02)
R W Brankin, University of Manchester | (Chapter D02)
R Bulirsch, Technische Hochschule, München | (Chapter S)
J C P Bus, CWI, Amsterdam | (Chapter C05)
P A Businger, Bell Telephone Laboratories | (Chapters F01 and F04)
B C Carlson, Iowa State University | (Chapter S)
R E Carlson, Lawrence Livermore National Laboratory | (Chapter E01)
A R Conn, University of Waterloo | (Chapter E02)
A Cook, Middlesex University | (Chapter G03)
M G Cox, National Physical Laboratory | (Chapters E01, E02, F01 and F04)
P J Culligan–Hensley, University of Western Australia | (Chapter C05)
B Curtis, National Physical Laboratory | (Chapter E02)
P Curtis, National Physical Laboratory | (Chapters E01 and E02)
C Daly, Lancaster University | (Chapter G13)
T J Dekker, University of Amsterdam | (Chapter C05)
L M Delves, University of Liverpool | (Chapter D01)
J W Demmel, New York University and University of California, Berkeley | (Chapters F07 and F08)
P M Dew, University of Leeds | (Chapter D03)
R Dias Da Cunha, University of Rio Grande do Sul | (Chapter F11)
P Dierckx, University of Leuven | (Chapter E02)
D R Divgi, Syracuse University | (Chapter G01)
D S Dodson, Convex Computer Corporation | (Chapter F06)
E de Doncker–Kapenga, University of Leuven and Western Michigan University | (Chapter D01)
J J Dongarra, Argonne National Laboratory, University of Tennessee and Oak Ridge National Laboratory | (Chapters F02, F06, F07 and F08)
J R Dormand, Teeside Polytechnic | (Chapter D02)
M Drew, University of Birmingham | (Chapter H)
I S Duff, AERE Harwell | (Chapters F01, F04 and F06)
B Ford, University of Nottingham | (Chapters E01, F01 and F02)
R Franke, Naval Postgraduate School | (Chapter E01)
F N Fritsch, Lawrence Livermore National Laboratory | (Chapter E01)
D Fritzshe, Bergische University of Wuppertal | (Chapter F11)
R M Furzeland, Shell Research Ltd | (Chapter D02)
B S Garbow, Argonne National Laboratory | (Chapters C05, C06 and F02)
W Gautschi, Purdue University | (Chapter S)
A C Genz, University of Kent and Washington State University | (Chapter D01)
M Giles, University of Oxford | (Chapter G01)
P E Gill, National Physical Laboratory, Stanford University and University of California at San Diego | (Chapter E04)
G Giunta, Argonne National Laboratory | (Chapter C06)
I Gladwell, University of Manchester and Southern Methodist University | (Chapters C05, D02, E01, E02, F01 and F04)
G H Golub, Stanford University | (Chapters F01 and F04)
P Gonnet, ETH Zürich and University of Oxford | (Chapter D01)
N I M Gould, National Physical Laboratory | (Chapter E04)
S R Graham, National Physical Laboratory | (Chapter E04)
P R Graves–Morris, University of Kent | (Chapters E01 and E02)
A Greenbaum, New York University | (Chapters F07 and F08)
P Griffiths, University of Oxford | (Chapter G02)
R G Grimes, Boeing Computer Services | (Chapter F06)
K Halstead, University of Warwick | (Chapter G01)
S J Hammarling, Middlesex Polytechnic and National Physical Laboratory | (Chapters E04, F01, F02 and F04)
D C Handscomb, University of Oxford | (Chapter G05)
R J Hanson, Sandia National Laboratories, Albuquerque | (Chapter F06)
J A Hartigan, Yale University | (Chapter G03)
R W Hatfield, University of Nottingham | (Chapter E01)
R I Hay, University of Manchester | (Chapters F01 and F04)
J G Hayes, National Physical Laboratory | (Chapters E01 and E02)
L Hayes, University of Oxford | (Chapters F01, F02, F03, F04 and F05)
F Hickernell, Illinois Institute of Technology | (Chapter G05)
N J Higham, University of Manchester | (Chapters F04, F07 and G02)
I D Hill, Medical Research Council | (Chapter G01)
K E Hillstrom, Argonne National Laboratory | (Chapter C05)
B T Hinde, National Physical Laboratory | (Chapter E04)
A C Hindmarsh, Lawrence Livermore National Laboratory | (Chapter D02)
D C Hoaglin, Harvard University | (Chapters G01 and G10)
S M Hodson, National Physical Laboratory | (Chapters D02 and E04)
H S Hong, Hong Kong Baptist University | (Chapter G05)
T R Hopkins, University of Kent | (Chapters E01 and F11)
M Hurley, Lancaster University | (Chapter G13)
M F Hutchinson, CSIRO, Canberra | (Chapter G10)
W Huyer, University of Vienna | (Chapter E05)
A N Jack, University of Nottingham | (Chapter E02)
D A H Jacobs, Central Electricity Research Laboratory | (Chapter D03)
S Joe, University of Waikato | (Chapter G05)
D K Kahaner, National Bureau of Standards | (Chapter D01)
M S Keech, University of Birmingham | (Chapter S)
M Kennedy, Queen's University, Belfast and Open University | (Chapter D01)
P D Kenward, National Physical Laboratory | (Chapters F01 and F02)
R Killick, Lancaster University | (Chapter G13)
D R Kincaid, University of Texas, Austin | (Chapter F06)
L Knüsel, University of Munich | (Chapter G01)
F T Krogh, Jet Propulsion Laboratory | (Chapter F06)
M Kočvara, University of Birmingham | (Chapter E04)
F Kuo, University of New South Wales | (Chapter G05)
C Laird, Purdue University | (Chapter E04)
C L Lawson, Jet Propulsion Laboratory | (Chapter F06)
M Lentini, California Institute of Technology | (Chapter D02)
S A Lill, University of Liverpool | (Chapter E04)
G R Lindfield, Massey University | (Chapter C05)
J Lloyd–Jones, University of Manchester | (Chapter G08)
E M R Long, National Physical Laboratory | (Chapter E04)
J N Lyness, Argonne National Laboratory | (Chapters C06, D01 and D04)
A McKenney, New York University | (Chapters F07 and F08)
N M Maclaren, University of Cambridge | (Chapters G01, G05 and M01)
J R Magnus, London School of Economics and Center for Economic Research, Tilburg | (Chapter G01)
K L Majumder, Space Applications Centre, Ahmedabad | (Chapter G01)
A Marazzi, University of Lausanne | (Chapters G02 and G07)
R S Martin, National Physical Laboratory | (Chapters F01, F02, F03 and F04)
G F Miller, National Physical Laboratory | (Chapters D01 and D05)
C B Moler, University of New Mexico | (Chapter F02)
J J Moré, Argonne National Laboratory | (Chapter C05)
C Mower, University of Manchester | (Chapter G02)
A Murli, University of Naples | (Chapter C06)
N Munksgaard, AERE Harwell | (Chapters F01 and F04)
B Muite, University of Michigan | (Chapter D02)
W Murray, National Physical Laboratory and Stanford University | (Chapter E04)
N Neumann, University of Göttingen | (Chapter G08)
A Neumaier, University of Vienna | (Chapter E05)
P Nicholson, University of Leeds | (Chapter G08)
P J Nikolai, US Air Force Flight Dynamics Laboratory | (Chapter F02)
E M Notis, Iowa State University | (Chapter S)
M R O'Donohoe, University of Cambridge | (Chapters C06 and D01)
S Ostrouchov, University of Tennessee | (Chapters F07 and F08)
C C Paige, McGill University | (Chapter F04)
J M Parkinson, University of Leeds | (Chapter E04)
B N Parlett, University of California, Berkeley | (Chapter F01)
T N L Patterson, Queen's University of Belfast | (Chapter D01)
A Paver, Middlesex University | (Chapter G01)
J Pearson, University of Oxford | (Chapter S)
S V Pennington, University of Leeds | (Chapter D03)
V Pereyra, University of Caracas | (Chapter D02)
B Pesaran, Bank of England | (Chapter G01)
G Peters, National Physical Laboratory | (Chapters F01, F02, F03 and F04)
A N Pettit, Loughborough University | (Chapters G01 and G08)
L Petzold, Lawrence Livermore National Laboratory | (Chapter D02)
C Phillips, University of Liverpool | (Chapter E02)
W Phillips, University of Oxford | (Chapters F01, F02, F03, F04 and F05)
R Piessens, University of Leuven | (Chapter D01)
R A Pitfield, National Physical Laboratory | (Chapter D03)
M J D Powell, University of Cambridge | (Chapter E04)
P J Prince, Teeside Polytechnic | (Chapter D02)
J D Pryce, University of Bristol | (Chapter D02)
G Radicati, IBM ECSEC, Rome | (Chapter F07)
M Razzaz, University of Birmingham | (Chapter S)
J K Reid, AERE Harwell | (Chapters D03, F01 and F04)
C Reinsch, Technische Hochschule, München | (Chapters F01 and F02)
R J Renka, Oak Ridge National Laboratory | (Chapter E01)
D G Rhead, University of Nottingham | (Chapter E04)
A Riley, University of Nottingham | (Chapter G04)
F D K Roberts, University of Victoria | (Chapter E02)
K Robinson, Rutherford Appleton Laboratory | (Chapter C06)
D Roose, University of Leuven | (Chapter D01)
J P Royston, Medical Research Council | (Chapter G01)
G Sande, University of Chicago | (Chapter C06)
M A Saunders, Stanford University | (Chapters E04 and F04)
B Scheichl, Technical University of Vienna | (Chapter C05)
K Schittkowski, University of Bayreuth | (Chapter H)
J L Schonfelder, University of Birmingham and University of Liverpool | (Chapter S)
W L Seward, University of Oxford and University of Waterloo | (Chapter D02)
L F Shampine, Sandia National Laboratories, Albuquerque and Southern Methodist University | (Chapter D02)
B L Shea, Aberystwyth University, London School of Economics and Manchester Metropolitan University | (Chapters G05, G11 and G13)
B W Silverman, University of Bath | (Chapter G10)
J W Sinclair, University of Dundee | (Chapter E02)
M A Singer, National Physical Laboratory | (Chapter E01)
A J Skellern, Loughborough University | (Chapters G01 and G08)
B T Smith, Argonne National Laboratory | (Chapter C02)
D C Sorensen, Argonne National Laboratory and Rice University | (Chapters F07 and F08)
M Stingl, University of Erlangen–Nuremberg | (Chapter E04)
N Strabić, University of Manchester | (Chapter G02)
P N Swarztrauber, National Centre for Atmospheric Research | (Chapter D03)
R A Sweet, University of Colorado at Denver | (Chapter D03)
A Swift, Massey University | (Chapter C05)
G T Symm, National Physical Laboratory | (Chapters D03, D05 and F01)
H J Symm, National Physical Laboratory | (Chapters F01 and F02)
D B Taylor, University of Edinburgh | (Chapters F01, F02, F03 and F04)
N Temme, CWI, Amsterdam | (Chapter S)
G E Thomas, University of Nottingham | (Chapter G01)
C P Thompson, AERE Harwell | (Chapter D03)
G Tunnicliffe–Wilson, Lancaster University | (Chapter G13)
C W Überhuber, Technical University Vienna | (Chapter D01)
P F Velleman, Cornell University | (Chapters G01 and G10)
J E Walsh, University of Manchester | (Chapters D03 and S)
H A Watts, Sandia National Laboratories, Albuquerque | (Chapter D02)
A Wächter, Northwestern University | (Chapter E04)
P Wesseling, Delft University of Technology | (Chapter D03)
J H Wilkinson, National Physical Laboratory | (Chapters F01, F02, F03 and F04)
D J Winstanley, University of Kent | (Chapter E01)
M A Wong, Yale University | (Chapter G03)
M H Wright, National Physical Laboratory and Stanford University | (Chapter E04)
I Wynne–Jones, Imperial College of Science and Technology | (Chapter C06)
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


How to Use the NAG Library and its Documentation : NAG Library, Mark 26

NAG Library

How to Use the NAG Library and its Documentation

▸▿ Contents

1 Library Identification
2 How to Find a NAG Library Routine
▸▿ 3 How to Use the NAG Library
▸▿ 3.1 Structure of the Library
3.1.1 Long Names for Library Routines
3.2 General Advice
▸▿ 3.3 Programming Advice
3.3.1 Alternative Routine Names
3.3.2 The NAG Fortran Environment
3.3.3 Direct and Reverse Communication Routines
▸▿ 3.4 Error Handling and the Argument IFAIL
3.4.1 Errors, Failure and Warning Conditions
3.4.2 The IFAIL Argument
3.4.3 Hard Fail Option
3.4.4 Soft Fail Option
3.4.5 Structure of the NAG Error Messages
3.4.6 Legacy Error Handling
3.5 Input/output in the Library
3.6 Auxiliary Routines as External Procedure Arguments
3.7 Dynamic Memory Allocation
3.8 License Management
3.9 Unexpected Errors
3.10 Calling the Library from Other Languages
▸▿ 3.11 Arithmetic Considerations and Reproducibility of Results
▸▿ 3.11.1 Bit-wise Reproducibility (BWR)
3.11.1.1 Vendor Math Libraries and Conditional Bitwise Reproducibility (CBWR)
▸▿ 3.12 Multithreading
▸▿ 3.12.1 Thread Safety
3.12.1.1 Routines with Routine Arguments
3.12.1.2 Input/Output
3.12.1.3 Implementation Issues
▸▿ 3.12.2 Parallelism
3.12.2.1 Introduction
3.12.2.2 How is Parallelism Used in the NAG Library?
3.12.3 Multithreaded Routines
▸▿ 4 How to Use NAG Documentation
4.1 Using the Manual
4.2 Structure of the Documentation
▸▿ 4.3 Specification of Arguments
4.3.1 Classification of Arguments (Intents)
4.3.2 Constraints and suggested values
4.3.3 Array Arguments
4.4 Implementation-dependent Information
4.5 Example Programs and Results
▸▿ 4.6 Online Documentation
▸▿ 4.6.1 HTML Format
4.6.1.1 Viewing HTML5 Files
4.6.1.2 Firefox (and other Mozilla based browsers)
4.6.1.3 Other Browsers
4.6.1.4 Navigating HTML5 Files
4.6.1.5 Printing HTML5 Files
4.6.1.6 Windows HTML Help
▸▿ 4.6.2 PDF Format
4.6.2.1 Viewing and Printing PDF Files
4.6.2.2 Navigating the PDF Files
5 NAG Library Design and Development
6 NAG Library Standards
7 References

1 Library Identification

Periodically a new Mark of the NAG Library is released: new routines are added, corrections and/or improvements are made to existing routines; and, occasionally, routines are withdrawn if they have been superseded by improved routines.
You must know which implementation, which precision and which mark and revision of the Library you are using or intend to use. To find out these Library details, you can run a program which calls the NAG Library routine A00AAF.
The program could be:
 USE nag_library, ONLY: a00aaf
 CALL a00aaf
 END
Alternatively, the example program for A00AAF can be run using the nag_example scripts supplied with your implementation (see the Users' Note for details).
An example of the output is:
  *** Start of NAG Library implementation details ***

  Implementation title: Linux, 64-bit, NAG Fortran (32-bit integers)
         Precision: FORTRAN double precision
      Product Code: FLL6A25D9L
          Mark: 25.0 (self-contained)

   *** End of NAG Library implementation details ***

2 How to Find a NAG Library Routine

All users both familiar or unfamiliar with this Library who are thinking of using a routine from it, are asked to please follow these instructions:
(a) | read How to Use the NAG Library and its Documentation as it provides valuable background information;
(b) | select an appropriate chapter or routine by using the online Keyword and GAMS Search;
(c) | read the relevant Chapter Introduction;
(d) | choose a routine, and read the routine document. If the routine does not after all meet your needs, return to step (b);
(e) | read the Users' Note for your implementation (this contains instructions on how to compile and run a program);
(f) | consult local documentation, which should be provided by your local support staff, about access to the Library on your computing system;
(g) | obtain a copy of the example program (see Section 4.5) for the particular routine of interest and experiment with it.
You should now be in a position to include a call to the routine in a program, and to attempt to compile and run it. You may of course need to refer back to the relevant documentation in the case of difficulties, for advice on assessment of results, and so on.
As you become familiar with the Library, some of steps (a) to (g) can be omitted, but it is useful to keep up to date with the following documents as they are subject to change:
  • How to Use the NAG Library and its Documentation;
  • the Chapter Introduction;
  • the routine document;
  • the Users' Note for your implementation.

3 How to Use the NAG Library

3.1 Structure of the Library

The NAG Library is a comprehensive collection of routines for the solution of numerical and statistical problems.
The Library is divided into chapters, each devoted to a branch of numerical analysis or statistics. Each chapter has a three-character name and a title, e.g.,
  • Chapter D01 – Quadrature
Exceptionally, Chapters H and S have one-character names. The chapters and their names are based on the ACM modified SHARE classification index (see ACM (1960–1976)).
All documented routines in the Library have six-character names, beginning with the characters of the chapter name, e.g.,
  • C06PCF
Note that the second and third characters are digits, not letters; e.g., 0 is the digit zero, not the letter O. The last letter of each routine name almost always appears as ‘F’ in the documentation. Chapters D03 and E04 have some routines whose last letter is ‘A’ rather than ‘F’. An ‘A’ version is always paired with an ‘F’ routine, the ‘A’ version being safe to use in a multithreaded environment, but otherwise having identical functionality to the ‘F’ version.
Chapter F06 (Linear Algebra Support Routines) contains all the Basic Linear Algebra Subprograms, BLAS (Dongarra et al. (1988) and Dongarra et al. (1990)), with NAG-style names as well as the actual BLAS names, e.g., F06PAF (DGEMV). The name in brackets is the equivalent double precision BLAS name. Chapter F16 contains some of the routines specified in the BLAS Technical Form (The BLAS Technical Forum Standard (2001) and Blackford et al. (2002)) and also some additional routines for integer valued vectors that are not in the standard. Some of the routines in Chapter F16 have both NAG-style names and BLAS names. Chapter F07 (Linear Equations (LAPACK)) and Chapter F08 (Least Squares and Eigenvalue Problems (LAPACK)) contain routines derived from the LAPACK project (Anderson et al. (1999)); also, Chapter F01 (Matrix Operations, Including Inversion) contains storage conversion routines derived from the LAPACK project. Like the BLAS, these routines have NAG-style names as well as LAPACK names, e.g., F07ADF (DGETRF). Details regarding these alternate names can be found in the relevant Chapter Introductions.
In order to take full advantage of machine-specific versions of BLAS and LAPACK routines provided by some computer hardware vendors, you are encouraged to use the BLAS and LAPACK names (e.g., DGEMV and DGETRF) rather than the corresponding NAG-style names (e.g., F06PAF (DGEMV) and F07ADF (DGETRF)) wherever possible in your programs.

3.1.1 Long Names for Library Routines

Each documented routine has, in addition to its short six-character name, a long name beginning with the root nagf_ and consisting of an underscore separated list of words. The long-name naming scheme has been chosen so that the long names group like routines together and group routines within a suite together.
The long name for each routine in a chapter is listed in the respective Chapter Contents page. The second word in the long name is fixed for each chapter, e.g., routines in Chapter D01 (Quadrature) all have long names that begin nagf_quad_.
Each chapter has a unique second word in its set of long names with the exception of Chapters F07 and F08 which share the same second word (lapack).
Note that the long names of BLAS and LAPACK routines, such as nagf_blas_dgemm, will not take advantage of machine-specific versions of BLAS and LAPACK. As mentioned in Section 3.1 you are recommended to use the plain BLAS or LAPACK name (in this case DGEMM) for performance reasons.
Routines that are marked for withdrawal have long names that have the third word withdraw. At subsequent marks of the library, any routine that becomes marked for withdrawal will have the third word withdraw inserted into its long name; the original long name will no longer be available for the given routine at that stage.
For those chapters that have both A and F versions of a routine, the long name for the F version is the same as that of the A version, but with an additional last word (old – signifying that the F version predates the A version).
It should be noted that the long names are implemented by the use of aliasing in the NAG Library interface block modules, and so long names are only accessible when calling the NAG Library from a Fortran program that USEs nag_library.mod.
Please refer to Section 3.3.1 for advice on supplying alternative routine names and, possibly, simplified routine interfaces.

3.2 General Advice

A NAG Library routine cannot be guaranteed to return meaningful results irrespective of the data supplied to it. Care and thought must be exercised in:
(a) | formulating the problem;
(b) | programming the use of Library routines;
(c) | assessing the significance of the results.
The Foreword to the Manual provides some further discussion of points (a) and (c); the remainder of this document is concerned with (b) and (c).

3.3 Programming Advice

The Library and its documentation are designed with the assumption that you will write a calling program in Fortran (although it may be called from other languages – see Section 3.10).
When programming a call to a routine, read the routine document carefully, especially the description of the arguments. This states clearly which arguments must have values assigned to them on entry to the routine, and which return useful values on exit. See Section 4.3 for further guidance.
The most common types of programming error in using the Library are:
  • incorrect arguments in a call to a Library routine;
  • calling the Library from a single precision program.
The USE of the nag_library MODULE will help detect or prevent some of these errors. For example, when using this, incorrect parameter types will be caught at compile time and using KIND=nag_wp in the type of real and complex variables will maintain consistency with the Library.
Therefore, if a call to a Library routine results in an unexpected error message from the system (or possibly from within the Library), check the following:
  • Have some actual array arguments been passed as different dummy arguments (i.e., an array appears more than once in the argument list with different INTENTs)?
  • Have all array arguments been dimensioned correctly?
Avoid the use of NAG-type names for your own program units or COMMON blocks: in general, do not use names which contain a three-character NAG chapter name embedded in them; they may clash with the names of an auxiliary routine or COMMON block used by the NAG Library.

3.3.1 Alternative Routine Names

If the Library is called from a Fortran program then it is possible to use alternative names for user-callable routines. This can be done via the ‘USE nag_library’ statement at the start of the (sub)program in which the Library routine is called. For example, you wish to use the name ‘BesselJ0’ instead of the Library name S17AEF. In this case the line
    USE nag_library, ONLY: s17aef
would be replaced by
    USE nag_library, ONLY: BesselJ0 => s17aef
The (sub)program would then use the name ‘BesselJ0’ in place of S17AEF and call it with the identical interface.
If Library routines are called from other environments then many such environments offer ways of ‘aliasing’ a routine name by a preferred alternative name.
For many of the Library routines with more complex interfaces it is likely that only a subset of the functionality is required and that some parameter values will always remain unchanged or will not be referenced. In such cases it may be preferable to write your own wrapper to the Library routine with a much simpler interface and with a preferred alternative name. For example, if you wish to integrate a system of stiff ordinary differential equations without root finding or intermediate output, you could create the simple interface wrapper to the more complicated D02EJF interface.
    SUBROUTINE BDFsolve(xend,y)
    USE nag_library, ONLY: nag_wp, d02ejf, d02ejw, d02ejx, d02ejy
    REAL(kind=nag_wp) :: xend, y(:)
    REAL(kind=nag_wp) :: tol, xstart
    INTEGER           :: ifail, iw, n
    CHARACTER         :: relabs
    REAL(kind=nag_wp), ALLOCATABLE :: w(:)

    n = SIZE(y)
    tol = 1.0e-3_nag_wp
    relabs = 'M'
    iw = (12+n)*n + 50
    ALLOCATE(w(iw))
    ifail = 0
    xstart = 0.0_nag_wp
    CALL d02ejf(xstart,xend,n,y,fcn,d02ejy,tol,relabs,d02ejx, &
                d02ejw,w,iw,ifail)
    RETURN
    END SUBROUTINE BDFsolve
The above example of a user-defined wrapper would be compiled and linked with a main program that would include the simple call:
    CALL BDFsolve(xend,y)

3.3.2 The NAG Fortran Environment

The environment for the NAG Library is defined by the nag_library MODULE. Certain routines require you to USE this to access named constants (e.g., nag_wp). It is recommended that you also USE the MODULE to enable checking of INTERFACEs in the Library.
The exact location of nag_library.mod is installation dependent; please see the Users' Note for your implementation.

3.3.3 Direct and Reverse Communication Routines

Routines in the Library that require a user-supplied function may be classified as either direct communication or reverse communication.
Direct communication routines require a user-supplied subroutine to be provided as an actual argument to the NAG Library routine. You must write this subroutine using a very rigid interface as specified in the relevant routine document. For the majority of applications this is the simplest and most convenient usage. Sometimes however this approach can be restrictive:
(i) | when the required format of the subroutine does not allow useful information to be passed conveniently to and from your calling program;
(ii) | when the direct communication routine is being called from another computer language which does not fully support procedure arguments in a way that is compatible with the Library.
These restrictions can be removed by using a reverse communication routine. Instead of obtaining the solution in one call, reverse communication routines perform one step of the solution process before returning to the calling program with an appropriate flag (irevcm) set. The value of irevcm determines whether the process has finished or whether fresh information is required. In the latter case the required information must be calculated before re-entering the reverse communication routine. Thus you have the responsibility for providing an iterative loop. Although reverse communication routines will typically be more complicated to use than direct communication equivalents they do provide greater flexibility for the evaluation of the function.

3.4 Error Handling and the Argument IFAIL

3.4.1 Errors, Failure and Warning Conditions

The error, failure or warning conditions considered here are those that can be detected by explicit coding in a Library routine. Such conditions must be anticipated by the author of the routine. They should not be confused with run-time errors detected by the compilation system, e.g., detection of overflow or failure to assign an initial value to a variable.
In the rest of this document we use the word ‘error’ to cover all types of error, failure or warning conditions detected by the routine. They fall roughly into three classes.
(i) | On entry to the routine the value of an argument is out of range. This means that it is not useful, or perhaps even meaningful, to begin computation.
(ii) | During computation the routine decides that it cannot yield the desired results, and indicates a failure condition. For example, a matrix inversion routine will indicate a failure condition if it considers that the matrix is singular and so cannot be inverted.
(iii) | Although the routine completes the computation and returns results, it cannot guarantee that the results are completely reliable; it therefore returns a warning. For example, an optimization routine may return a warning if it cannot guarantee that it has found a local minimum.
All three classes of errors are handled in the same way by the Library.
Each error which can be detected by a Library routine is associated with a number. Some numbers such as those associated with a failure in dynamic memory allocation (see Section 3.7) or detecting a valid licence (Section 3.8) are the same for all Library routines and may not be listed in individual routine documents. Recently added routines have standardized on using the same number for unexpected error exits (Section 3.9). All other numbers, with explanations of the errors, are listed in Section 6 (Error Indicators and Warnings) in the routine document. Unless the document specifically states to the contrary, you should not assume that the routine necessarily tests for the occurrence of the errors in their order of error number, i.e., the detection of an error does not imply that other errors have or have not been detected.

3.4.2 The IFAIL Argument

Most of the NAG Library routines which can be called directly by you have an argument called IFAIL. This argument is concerned with the NAG Library error trapping mechanism (and, for some routines, with controlling the output of error messages and advisory messages).
IFAIL has two purposes:
(i) | to allow you to specify what action the Library routine should take if an error is detected;
(ii) | to inform you of the outcome of the call of the routine.
For purpose (i), you must assign a value to IFAIL before the call to the Library routine. Since IFAIL is reset by the routine for purpose (ii), the argument must be the name of a variable, not a literal or constant.
The value assigned to IFAIL before entry should be either 0 (hard fail option), or 1 or -1 (soft fail option). If after completing its computation the routine has not detected an error, IFAIL is reset to 0 to indicate a successful call. Control returns to the calling program in the normal way. If the routine does detect an error, its action depends on whether the hard or soft fail option was chosen. If IFAIL is set to any value other than -1, 0 or 1 before calling the Library routine, a default of IFAIL=1 is assumed.

3.4.3 Hard Fail Option

If you set IFAIL to 0 before calling the Library routine, execution of the program will terminate if the routine detects an error. Before the program is stopped, this error message is output:
** ABNORMAL EXIT from NAG Library routine XXXXXX: IFAIL = n
** NAG hard failure - execution terminated
where XXXXXX is the routine name, and n is the number associated with the detected error. An explanation of error number n is given in Section 6 of the routine document XXXXXX.
In addition, most routines output explanatory error messages immediately before the standard termination message shown above.
The hard fail option should be selected if you are in any doubt about continuing the execution of the program after an unsuccessful call to a NAG Library routine. For environments where it might be inappropriate to halt program execution when an error is detected it is recommended that the hard fail option is not used.

3.4.4 Soft Fail Option

To select this option, you must set IFAIL to 1 or -1 before calling the Library routine. Note that IFAIL=1 is assumed when IFAIL is set to an invalid value before calling the Library routine.
If the routine detects an error, IFAIL is reset to the associated error number; further computation within the routine is suspended and control returns to the calling program.
If you set IFAIL to 1, then no error message is output (silent exit). If the output of error messages is undesirable, then silent exit is recommended.
If you set IFAIL to -1 (noisy exit), then before control is returned to the calling program, the following error message is output:
** ABNORMAL EXIT from NAG Library routine XXXXXX: IFAIL = n
** NAG soft failure - control returned
In addition, most routines output explanatory error messages immediately before the above standard message.
It is most important to test the value of IFAIL on exit if the soft fail option is selected. A nonzero exit value of IFAIL implies that the call was not successful so it is imperative that your program be coded to take appropriate action. That action may simply be to print IFAIL with an explanatory caption and then terminate the program. Many of the example programs in Section 9 of the routine documents have IFAIL-exit tests of this form. In the more ambitious case, where you wish your program to continue, it is essential that the program can branch to a point at which it is sensible to resume computation.
The soft fail option puts the onus on you to handle any errors detected by the Library routine. With the proviso that you are able to implement it properly, it is clearly more flexible than the hard fail option since it allows computation to continue in the case of errors. In particular there are at least two cases where its flexibility is useful:
(i) | where additional information about the error or the progress of computation is returned via some of the other arguments;
(ii) | in some routines, ‘partial’ success can be achieved, e.g., a probable solution found but not all conditions fully satisfied, so the routine returns a warning. On the basis of the advice in Section 6 and elsewhere in the routine document, you may decide that this partially successful call is adequate for certain purposes.

3.4.5 Structure of the NAG Error Messages

The notation value appearing in the documented error message is a place holder that will be populated by the value of a variable, argument name or some other piece of information when that error message is displayed.

3.4.6 Legacy Error Handling

A few routines (introduced mainly at Marks 7 and 8) use IFAIL in a nonstandard way to control the output of error messages, and also of advisory messages (see Chapter X04). In those routines IFAIL is regarded as an integer of the form 100 c+10 b+a, where a and b are either 0 or 1 and have the following significance:
a=0: hard failure | a=1: soft failure
b=0: silent exit | b=1: noisy exit
Details are given in the documents of the relevant routines; for those routines this alternative use of IFAIL remains valid.

3.5 Input/output in the Library

Most NAG Library routines perform no output to an external file, except possibly to output an error message. All error messages are written to a logical error message unit. This unit number (which is set by default to 6 in most implementations) can be changed by calling the Library routine X04AAF.
Some NAG Library routines may optionally output their final results, or intermediate results to monitor the course of computation. In general, output other than error messages is written to a logical advisory message unit. This unit number (which is also set by default to 6 in most implementations) can be changed by calling the Library routine X04ABF. Although it is logically distinct from the error message unit, in practice the two unit numbers may be the same. Suites of routines with an option setting facility usually allow this unit number to be specified directly as an option.
All output from the Library is appropriately formatted.
There are only a few Library routines which perform input from an external file. These examples occur in Chapters E04, E05 and H. The unit number of the external file is an argument to the routine, and all input is formatted.
You must ensure that the relevant Fortran unit numbers are associated with the desired external files, either by an OPEN statement in your calling program, or by operating system commands.

3.6 Auxiliary Routines as External Procedure Arguments

In addition to those Library routines which are documented and are intended to be called by you directly, the Library also contains many auxiliary routines.
In general, you need not be concerned with them at all, although you may be made aware of their existence if, for example, you examine a memory map of an executable program which calls NAG routines. The only exception is that when calling some NAG Library routines you may be required or allowed to supply the name of an auxiliary routine from the NAG Library as an external procedure argument. The routine documents give the necessary details. In such cases, you only need to supply the name of the routine; you never need to know details of its argument list.
NAG auxiliary routines have names which are similar to the name of the documented routine(s) to which they are related, but with last letter ‘Z’, ‘Y’, and so on, e.g.,
  • G13AFZ is an auxiliary routine called by G13AFF.
A few chapters contain auxiliary routines whose names are obtained by adding 50 to the second and third characters of the chapter name. For instance, Chapter E04 has an auxiliary routine with the name E54NFU which is normally used as the actual argument for the QPHESS argument of E04NFA; the corresponding name to be used with E04NFF is E04NFU.

3.7 Dynamic Memory Allocation

Some NAG Library routines perform dynamic memory allocation to simplify their interfaces. Where possible, the amount of memory allocated by a routine will be given in the routine document (usually as a function of routine arguments). All memory allocated by NAG routines is deallocated before exit.
In the case where a routine detects a failure to dynamically allocate sufficient memory, the routine will set an error condition, by setting IFAIL=-999, and exit with an appropriate error message.

3.8 License Management

If your implementation is license managed then your local site will have details on how the license management is implemented; please contact your site installer for details. To determine whether a valid license is available on your machine run the example program for A00ACF.
Should a valid license not be found when calling license managed routines from the Library then the routine will set an error condition, by setting IFAIL=-399 , and exit with an appropriate error message. On Unix based systems, the appropriate environment variables should then be checked (e.g., NAG_KUSARI_FILE) to make sure this points to the licence file containing a valid licence, and the licence file should be checked for any obvious errors (e.g., the licence refers to a different implementation). If everything appears to be correct then please contact NAG (see Support from NAG for details).

3.9 Unexpected Errors

Internal calls to Library routines are checked for error exits even when these exits are not to be expected. Should an unexpected error exit occur the routine will set an error condition by setting IFAIL and exit with an appropriate error message. Historically, the number returned in IFAIL was particular to that routine and differing numbers could be used for this purpose. However, recently added routines have standardized by setting IFAIL=-99 for unexpected error detection.

3.10 Calling the Library from Other Languages

In general the NAG Library can be called from other computer languages (such as C and Visual Basic) provided that appropriate mappings exist between their data types).
NAG has produced C Header Files which comprise of a set of header files, indicating the match between C and Fortran data types for various compilers, documentation and examples. The documentation, examples and C Header Files are available from the NAG Web sites (see Support from NAG).
The Dynamic Link Library (DLL) implementation can be called in a straightforward manner from a number of languages and environments, e.g., Visual Basic, Visual Basic for Applications (Excel), Fortran, C and C++. Guidance on this is provided in the Users' Note for the NAG Library DLLs. Further details can be found on the NAG Web sites.

3.11 Arithmetic Considerations and Reproducibility of Results

The results obtained when calling a NAG Library routine depend not only on the algorithm used to solve the problem, but also on the compiler used to build the library, compiler run-time libraries and also the arithmetic properties of the machine on which the code is run.
Historically, different kinds of computer hardware tended to have different kinds of arithmetic. Some machines would store floating-point numbers using a base 16 significand and exponent system, others would use base 2, and some even used base 8 or 10. Such differences caused major headaches for software library providers because code that worked well on one arithmetic system might not behave in exactly the same way on another. This meant that great care had to be taken to make the library code portable.
In addition, it was not unheard of for machine arithmetic to have flaws or errors where basic operations such as multiplication or division could sometimes give incorrect results, especially on numbers that were in some way ‘extreme’, such as being very large or small.
After the first of the IEEE standards for floating-point arithmetic (ANSI/IEEE (1985)) was introduced in the 1980s, the situation improved greatly. Nowadays most significant hardware, and certainly most hardware that NAG libraries run on, will use IEEE-style base 2 arithmetic. This makes production of portable code easier, but there are still problems, partly due to the latitude allowed by the IEEE standards. For example, hardware which uses extra-precise 80-bit internal registers for arithmetic, as originally introduced in the Intel 8087 coprocessor in the 1980s, behaves slightly differently from hardware that uses 64-bit registers, particularly if a compiler generates optimized code which holds arithmetic subexpressions in the extra-precise registers.
Since, for performance reasons, computer arithmetic is generally finite precision (as is certainly the case for IEEE standard arithmetic) most of the numerical methods implemented by NAG Library routines can only return an approximation to the true solution, simply due to accumulation of rounding errors.
It should therefore be clear that running a program which calls a NAG Library routine with the same data on two different machines can give different results, due to compiler, hardware and run-time library considerations. Usually these differences are small – it may be that a result computed on one machine differs only in the last few significant bits from the same result computed on another machine – for example, when solving a well-conditioned set of linear equations on two different machines. Occasionally small differences may be magnified, for example if a conditional test depends on an imprecise result. A routine that searches for a mininum of an optimization problem may converge to a different local minimum, but in general, so long as the routine's documentation doesn't claim that the same local minimum will always be obtained, this should be acceptable. Even if an algorithm converges to the same local minimum, arithmetic differences may mean that a different number of iterations is taken to get there.
Modern hardware and optimizing compilers have introduced further scope for arithmetic quirks. An example is in the use of Streaming SIMD Extension (SSE) instructions. These low-level machine instructions allow hardware to operate on more than one number in parallel, if your compiler is smart enough to generate and use them correctly, or if you hand-code your own assembly language routines.
SSE instructions enable low-level parallelism of floating-point arithmetic operations. For example, a 128-bit SSE register can hold two 64-bit double precision (or four 32-bit single precision) numbers at the same time, and operate on them all simultaneously. This can lead to big time savings when working on large amounts of data.
But this may come at a price. Efficient use of SSE instructions can sometimes depend on exactly how the memory used to store data is aligned. Some SSE instructions for moving data to and from memory need memory to be aligned on a 16-byte boundary. If it happens that the memory (for example, a pointer to an array of numbers) that a NAG routine uses is not aligned nicely, then it may not be possible to use those SSE instructions. An optimizing compiler might well generate two instruction streams, one for when it detects that memory is aligned and one for when it is not.
An example should serve to make things clearer. Suppose we wish to compute the inner product of two vectors, X and Y, each of length N. The inner product (or dot product) of two vectors is computed by multiplying together corresponding elements of the two vectors, and summing the individual products to get the result. A routine compiled by a good optimizing compiler would load numbers two or four at a time, multiply them together two or four at a time, and accumulate the results into the final result.
But if the memory is not nicely aligned – and it may well not be – the compiler needs to generate a different code path to deal with the situation. Here the result will take longer to get because the products must be computed and accumulated one at a time. At run-time, the code checks whether it can take the fast path or not, and works appropriately.
The problem is that by altering the order of the accumulations, we are quite possibly changing the final result, simply due to rounding differences when working with finite precision computer arithmetic. Instead of getting the inner product
s = x 1 × y 1 + x 2 × y 2 + x 3 × y 3 + ⋯ + xn × yn
we may get
s = x 1 × y 1 + x 3 × y 3 + x 2 × y 2 + x 4 × y 4 + ⋯ .
It is likely that the result will be just as accurate either way – neither result will be precise due to finite arithmetic – but they may differ by a tiny amount. And if that tiny difference leads to a different decision being made by the code that called the inner product routine, the difference may be magnified.
Furthermore, it is possible that the same program running with bitwise identical data on the same machine may give different results when run twice in a row simply because, when the program is loaded, by chance some piece of memory may or may not be aligned on a particular boundary. Such non-deterministic results can be frustrating if you depend on always getting identical results for the same data.
On even newer hardware, AVX instructions use 256-bit and 512-bit registers, and can therefore operate on more numbers at a time. For AVX instructions, memory may need to be 32-byte aligned.
Some memory used by NAG Library routines is allocated inside the NAG Library. In order to minimize differences due to effects like that described above, we can try to make sure the memory is always aligned nicely – for example, by use of more controllable memory allocation routines where available – but that is not always possible since it partly depends on the support of the compiler.
Of course, no Library routine has control over memory you have allocated before being passed to the routine. If you do observe non-deterministic results which you suspect are due to memory considerations, and you are unable to accept this variation, then you are advised to make sure that any memory you allocate is aligned nicely; unfortunately, precisely how you do this is dependent on your system, but you may be able to get advice through NAG's usual support channels (see Support from NAG).
Parallelism, coming from a multithreaded implementation of the NAG Library and/or a multithreaded vendor library is another potential source of non-determinism in numerical results. Some routines may give different results when run on different numbers of cores, or even different results when a calculation is repeated on the same number of cores. Where reproducibility of results is vital, a purely serial NAG library, without parallelism in either NAG routines or calls to parallel vendor library routines will generally be available in an appropriate implementation, and may be the best choice. You are advised to consult NAG (see Support from NAG) for advice.

3.11.1 Bit-wise Reproducibility (BWR)

Mathematical operations on fixed-length floating point numbers (e.g., 32-bit floats or 64-bit doubles) are not associative. This means that a computer may produce different results for a+b+c and a+b+c. For example, an IEEE 754 32-bit floating point number has a mantissa of 23 bits. Therefore in this number format 224+1=224, which means that for instance 224+1-224=0 while 224 +1-224=1. BWR is a term which refers to the case in which a given computer program (e.g., a set of source codes) produces bit-for-bit the exact same answer in different computing environments such as
1. | Different operating systems (e.g., answers produced on Windows vs answers produced on Linux).
2. | Different CPU architectures (e.g., Intel vs AMD or Intel Sandy Bridge vs Intel Ivy Bridge etc.).
3. | Different compiler versions.
4. | Different numbers of threads.
Users often desire BWR however it is extremely difficult to achieve. Typically you should ensure that:
(a) | Instructions are always executed in exactly the same order.
(b) | No advanced CPU features are used which may not be available on other processors (e.g., SSE3, SSE4, AVX).
(c) | A fixed number of threads is always used.
Often condition (a) is equivalent to compiling with no (or very limited) compiler optimizations, since newer versions of compilers typically improve their code optimization algorithms, which means one version of a compiler may optimize a set of operations one way while the next version may optimize it a different way. Condition (b) typically means that only basic SSE instructions are allowed, such as are supported across the widest range of processors and the enhanced SIMD instructions present in newer processors are not exploited.
The result is that to achieve BWR across a wide range of computing environments one often has to sacrifice a lot of performance.
3.11.1.1 Vendor Math Libraries and Conditional Bitwise Reproducibility (CBWR)
An implementation of the NAG Library that is not self-contained will make calls to an appropriate vendor library containing, in particular, high performance linear algebra routines. The NAG Library has no direct control over BWR with respect to results obtained from calls to the vendor library. However, for at least one such vendor library, CBWR has been introduced such that if an environment variable is set and a set of conditions adhered to in the code calling the vendor library then BWR can be forced. Where CBWR is available for a vendor library used by an implementation of the NAG Library, details will be given in the Users' Note for that implementation.
It should be noted that many NAG routines do not adhere to the conditions set out by vendor library CBWR and so it may not be possible to ensure BWR for all NAG Library routines across different CPU architectures for implementations that are not self-contained.

3.12 Multithreading

3.12.1 Thread Safety

In multi-threaded applications a team of threads each process instructions independently while sharing the same memory address space. A thread safe program ensures that any data shared by these threads, such as global variables, is not accessed simultaneously which compromises results. This can be ensured through appropriate synchronization, such as that found in OpenMP. Most routines in the NAG Fortran Library are thread safe, however there are some routines that are not thread safe as they use global variables (such as module variables, common blocks or variables with the SAVE attribute). Please consult Section 8 of each routine document for further information. A list of routines which are thread unsafe is available in the document Thread Unsafe Routines.
In the NAG Fortran Library there are some pairs of routines which share the same root name, for example, the routines E04UCF/E04UCA. Each routine in the pair has exactly the same functionality, except that one of them has additional parameters in order to make it safe for use in multithreaded applications (i.e., thread safe). The thread safe routine has a different last character in the name in place of the usual character (typically ‘A’ instead of ‘F’). Such pairs are documented in a single routine document and are listed in the individual Chapter Contents.
3.12.1.1 Routines with Routine Arguments
Some Library routines require you to supply a routine and to pass the name of the routine as an actual argument in the call to the Library routine. For many of these Library routines, the supplied routine interface includes array parameters (called IUSER and RUSER) specifically for you to pass information to the supplied routine without the need for global variables.
In the Fortran Library if the interfaces of a pair of thread safe (ending ‘A’) and non-thread safe (ending ‘F’) routines contain a user-supplied routine argument then the ‘A’ routine will contain the additional array arguments IUSER and RUSER (possibly plus others for internal use). In some cases the ‘A’ routine may need to be initialized by a separate initialization routine; this requirement will be clearly documented.
If you need to provide your supplied routine with more information than can be given via the interface argument list, then you are advised to check, in the relevant Chapter Introduction, whether the Library routine you intend to call has an equivalent reverse communication interface. These have been designed specifically for problems where user-supplied routine interfaces are not flexible enough for a given problem, and their use should eliminate the need to provide data through global variables. Where reverse communication interfaces are not available, it is usual to use global variables containing the required data that is accessible from both the supplied routine and from the calling program. It is thread safe to do this only if any global data referenced is updated using appropriate synchronisation, thus avoiding the possibility of simultaneous modification by different threads.
Thread safety of user-supplied routines is also an issue with a number of routines in multi-threaded implementations of the NAG Library, which may internally parallelize around the calls to the user-supplied routines. This issue affects not just global variables but also how the IUSER and RUSER arrays may be used. In these cases, synchronisation may be needed to ensure thread safety. Chapter X06 provides routines which can be used in your supplied routine to determine whether it is being called from within an OpenMP parallel region. If you are in doubt over the thread safety of your program you are advised to contact NAG for assistance.
3.12.1.2 Input/Output
The Library contains routines for setting the current error and advisory message unit numbers (X04AAF and X04ABF). These routines use the SAVE statement to retain the values of the current unit numbers between calls. It is therefore not advisable for different threads of a multithreaded program to set the message unit numbers to different values. A consequence of this is that error or advisory messages output simultaneously may become garbled, and in any event there is no indication of which thread produces which message. You are therefore advised always to select the ‘soft failure’ mechanism without any error message (IFAIL=+1, see Section 3.4) on entry to each NAG Library routine called from a multithreaded application; it is then essential that the value of IFAIL be tested on return to the application.
3.12.1.3 Implementation Issues
In very rare cases we are unable to guarantee the thread safety of a particular specific implementation. Note also that in some implementations, the Library is linked with one or more vendor libraries to provide, for example, efficient BLAS functions. NAG cannot guarantee that any such vendor library is thread safe. Please consult the Users' Note for your implementation for any additional implementation-specific information.

3.12.2 Parallelism

3.12.2.1 Introduction
The time taken to execute a routine from the NAG Library has traditionally depended, to a large degree, on the serial performance capabilities of the processor being used. In an effort to go beyond the performance limitations of a single core processor, multithreaded implementations of the NAG Library are available. These implementations divide the computational workload of some routines between multiple cores and executes these tasks in parallel. Traditionally, such systems consisted of a small number of processors each with a single core. Improvements in the performance capabilities of these processors happened in line with increases in clock frequencies. However, this increase reached a limit which meant that processor designers had to find another way in which to improve performance; this led to the development of multicore processors, which are now ubiquitous. Instead of consisting of a single compute core, multicore processors consist of two or more, which typically comprise at least a Central Processing Unit and a small cache. Thus making effective use of parallelism, wherever possible, has become imperative in order to maximize the performance potential of modern hardware resources, and the multithreaded implementations.
The effectiveness of parallelism can be measured by how much faster a parallel program is compared to an equivalent serial program. This is called the parallel speedup. If a serial program has been parallelized then the speedup of the parallel implementation of the program is defined by dividing the time taken by the original serial program on a given problem by the time taken by the parallel program using n cores to compute the same problem. Ideal speedup is obtained when this value is n (i.e., when the parallel program takes 1 nth the time of the original serial program). If speedup of the parallel program is close to ideal for increasing values of n then we say the program has good scalability.
The scalability of a parallel program may be less than the ideal value because of two factors:
(a) | the overheads introduced as part of the parallel implementation, and
(b) | inherently serial parts of the program.
Overheads include communication and synchronisation as well as any extra setup required to allow parallelism. Such overheads depend on the efficiency of the compiler and operating system libraries and the underlying hardware. The impact on performance of inherently serial fractions of a program is explained theoretically (i.e., assuming an idealised system in which overheads are zero) by Amdahl's law. Amdahl's law places an upper bound on the speedup of a parallel program with a given inherently serial fraction. If r is the parallelizable fraction of a program and s=1-r is the inherently serial fraction then the speedup using n sub-tasks, Sn, satisfies the following:
S n ≤ 1 s+ r n
Thus, for example, this says that a program with a serial fraction of one quarter can only ever achieve a speedup of 4 since as n→∞, Sn≤4.
Parallelism may be utilised on two classes of systems: shared memory and distributed memory machines, which require different programming techniques. Distributed memory machines are composed of processors located in multiple components which each have their own memory space and are connected by a network. Communication and synchronisation between these components is explicit. Shared memory machines have multiple processors (or a single multicore processor) which can all access the same memory space, and this shared memory is used for communication and synchronisation. The NAG Library makes use of shared memory parallelism using OpenMP as described in Section 3.12.2.2.
Parallel programs which use OpenMP create (or "fork") a number of threads from a single process when required at run-time. (Programs which make use of shared memory parallelism are also called multithreaded programs.) The threads form a team comprising of a single master thread and a number of slave threads. These threads are capable of executing program instructions independently of one another in parallel. Once the parallel work has been completed the slave threads return control to the master thread and become inactive (or "join") until the next parallel region of work. The threads share the same memory address space, i.e., that of the parent process, and this shared memory is used for communication and synchronisation. OpenMP provides some mechanisms for access control so that, as well as allowing all threads to access shared variables, it is possible for each thread to have private copies of other variables that only it can access. Something to be aware of for multithreaded programs, compared to serial ones, is that identical results cannot be guaranteed, nor should be expected. Identical results are often impossible in a parallel program since using different numbers of threads may cause floating-point arithmetic to be evaluated in a different (but equally valid) order, thus changing the accumulation of rounding errors. For a more in-depth discussion of reproducibility of results see Section 3.11.
3.12.2.2 How is Parallelism Used in the NAG Library?
The multithreaded implementations differ from the serial implementations of the NAG Library in that it makes use of multithreading through use of OpenMP, which is a portable specification for shared memory programming that is available in many different compilers on a wide range of different hardware platforms (see OpenMP).
Note that not all routines are parallelized; you should check Section 8 of the routine documents to find details about parallelism and performance of routines of interest.
There are two situations in which a call to a routine in the NAG Library makes use of multithreading:
1. | The routine being called is a NAG-specific routine that has been threaded using OpenMP, or that internally calls another NAG-specific routine that is threaded. This applies to multithreaded implementations of the NAG Library only.
2. | The routine being called calls through to BLAS or LAPACK routines. The vendor library recommended for use with your implementation of the NAG Library (whether the NAG Library is threaded or not) may be threaded. Please consult the Users' Note for further information.
A complete list of all the routines in the NAG Library, and their threaded status is given in Section 3.12.3.
It is useful to understand how OpenMP is used within the Library in order to avoid the potential pitfalls which lead to making inefficient use of the Library.
A call to a threaded NAG-specific routine may, depending on input and at one or more points during execution, use OpenMP to create a team of threads for a parallel region of work. The team of threads will fork at the start of the parallel region before joining at the end of the parallel region. Both the fork and the join will happen internally within the routine call. However, there are situations in which the teams of threads may be made available to OpenMP directives in your code via user-supplied subprograms, we refer to directives not contained within a parallel region as orphaned directives. (See Section 8 of the routine documents for further information.) Furthermore, OpenMP constructs within NAG routines are executed by teams of threads created within the NAG code, that is, there are no orphaned directives in the Library itself. Throughout this documentation we assume the use of the recommended compiler as given in the Users' Note, and in particular the use of a single OpenMP run-time library. Thus all OpenMP environment variables will apply to your own code and to NAG routines. However, they may not be respected by vendor libraries that have a mechanism for overriding them. NAG provides routines in Chapter X06 to control threads for your whole program, including any specific to a vendor library being called by NAG. You should take care when calling these NAG routines from within your own parallel regions, since if nested parallelism is enabled (it is disabled by default) the NAG routine will fork-and-join a team of threads for each calling thread, which may lead to contention on system resources and very poor performance. Poor performance due to contention can also occur if the number of threads requested exceeds the number of physical cores in your machine, or if some hardware resources are busy executing other processes (which may belong to other users in a shared system). For these reasons you should be aware of the number of physical cores available to your program on your machine, and use this information in selecting a number of threads which minimizes contention on resources. Please read the Users' Note for advice about setting the number of threads to use, or contact NAG (see Support from NAG) for advice.
If you are calling multithreaded NAG routines from within another threading mechanism you need to be aware of whether or not this threading mechanism is compatible with the OpenMP compiler runtime used to build the multithreaded implementation of the NAG Library on your platform(s) of choice. The Users' Note document for each of the implementations in question will include some guidance on this, and you should contact NAG for further advice if required.
Parallelism is used in many places throughout the NAG Library since, although many routines have not been the focus of parallel development by NAG, they may benefit by calling routines that have, and/or by calling parallel vendor routines (e.g., BLAS, LAPACK). Thus, the performance improvement due to multithreading, if any, will vary depending upon which routine is called, problem sizes and other parameters, system design and operating system configuration. If you frequently call a routine with similar data sizes and other parameters, it may be worthwhile to experiment with different numbers of threads to determine the choice that gives optimal performance. Please contact NAG for further advice if required.
As a general guide, many key routines in the following areas are known to benefit from shared memory parallelism:
  • Dense and Sparse Linear Algebra
  • FFTs
  • Random Number Generators
  • Quadrature
  • Partial Differential Equations
  • Interpolation
  • Curve and Surface Fitting
  • Correlation and Regression Analysis
  • Multivariate Methods
  • Time Series Analysis
  • Financial Option Pricing
  • Global Optimization
  • Wavelets

3.12.3 Multithreaded Routines

Many routines are threaded using OpenMP in multithreaded implementations of the NAG Library. These implementations are denoted by having a product code of the form 'FS_______', rather than 'FL_______' for serial NAG Library implementations. Please consult Section 8 of each routine document for further information. A list of routines which have been threaded by NAG is available in the document Multithreaded Routines. The list also includes routines which internally call BLAS or LAPACK routines, which may be threaded within the vendor library used by both serial and multithreaded NAG Library implementations. You are advised to consult the documentation for the vendor library for further information. Please consult the Users' Note for your implementation for any additional implementation-specific information.

4 How to Use NAG Documentation

4.1 Using the Manual

The Manual is designed to serve the following functions for the NAG Library:
  • to give background information about different areas of numerical and statistical computation;
  • to advise on the choice of the most suitable NAG Library routine or routines to solve a particular problem;
  • to give all the information needed to call a NAG Library routine correctly from a Fortran program, and to assess the results.
At the beginning of the Manual are some general introductory documents which provide some background and additional information.
The document entitled ‘Mark 26 NAG Fortran Library News’ provides details of new routines added, details of routines scheduled for withdrawal and details of routines withdrawn at this mark.
The document entitled ‘Advice on Replacement Calls for Withdrawn/Superseded Routines’ provides advice on how to modify your program.
The online documentation includes a Keyword and GAMS Search which provides you with a form to search the Library for keywords.
Having found a likely chapter or routine, you should read the corresponding Chapter Introduction, which gives background information about that area of numerical computation, and recommendations on the choice of a routine, including indexes, tables and decision trees.
When you have chosen a routine, you must consult the routine document. Each routine document is essentially self-contained (it may, however, contain references to related documents). It includes a description of the method, detailed specifications of each argument, explanations of each error exit, remarks on accuracy, and (in most cases) an example program to illustrate the use of the routine.

4.2 Structure of the Documentation

The NAG Library Manual is the principal documentation for the NAG Library. It has the same chapter structure as the Library: each chapter of routines in the Library has a corresponding chapter (of the same name) in the Manual. The chapters occur in alphanumeric order. General introductory documents appear at the beginning of the Manual.
Each chapter consists of the following documents:
  • Chapter Contents, e.g., Chapter D01;
  • Chapter Introduction, e.g., the D01 Chapter Introduction;
  • Routine Documents, one for each documented routine in the chapter.
A routine document has the same name as the routine which it describes. Within each chapter, routine documents occur in alphanumeric order of short names. For those chapters that have both ‘A’ and ‘F’ versions of a routine, the routine descriptions are combined into one routine document.
All routine documents have the same structure consisting of ten numbered sections:
1. | Purpose
2. | Specification
3. | Description
4. | References
5. | Arguments (see Section 4.3)
6. | Error Indicators and Warnings
7. | Accuracy
8. | Parallelism and Performance
9. | Further Comments
10. | Example (see Section 4.5)
In some documents (notably Chapters E04, E05 and H) there are a further three sections:
11. | Algorithmic Details
12. | Optional Parameters
13. | Description of Monitoring Information
The sections numbered 11. and 13. above are optional; thus, the section titled Optional Parameters may appear as (the possibly final) Section 11.

4.3 Specification of Arguments

Section 5 of each routine document contains the specification of the arguments, in the order of their appearance in the argument list.

4.3.1 Classification of Arguments (Intents)

Arguments are classified as follows.
Input: you must assign values to these arguments on or before entry to the routine, and these values are unchanged on exit from the routine.
Output: you need not assign values to these arguments before entry to the routine; the routine may assign values to them.
Input/Output: you must assign values to these arguments before entry to the routine, and the routine may then change these values.
Workspace: array arguments which are used as workspace by the routine. You must supply arrays of the correct type and dimension. In general, you need not be concerned with their contents.
Communication Array: arguments which are used to communicate data from one routine call to another.
External Procedure: a routine which must be supplied (e.g., to evaluate an integrand or to print intermediate output). Usually it must be supplied as part of your calling program, in which case its specification includes full details of its argument list and specifications of its arguments (all enclosed in a box). Its arguments are classified in the same way as those of the Library routine, but because you must write the procedure rather than call it, the significance of the classification is different.
  • Input: values may be supplied on entry, which your procedure must not change.
  • Output: you may or must assign values to these arguments before exit from your procedure.
  • Input/Output: values may be supplied on entry, and you may or must assign values to them before exit from your procedure.
Occasionally, as mentioned in Section 3.6, the procedure can be supplied from the NAG Library, and then you only need to know its name.
User Workspace: array arguments which are passed by the Library routine to an external procedure argument. They are not used by the routine, but you may use them to pass information between your calling program and the external procedure.
Dummy: a simple variable which is not used by the routine. A variable or constant of the correct type must be supplied, but its value need not be set. (A dummy argument is usually an argument which was required by an earlier version of the routine and is retained in the argument list for compatibility.)

4.3.2 Constraints and suggested values

The word ‘Constraint:’ or ‘Constraints:’ in the specification of an Input argument introduces a statement of the range of valid values for that argument, e.g.,
  • Constraint: N>0.
If the routine is called with an invalid value for the argument (e.g., N=0), the routine will usually take an error exit, returning a nonzero value of IFAIL (see Section 3.4).
Constraints on arguments of type CHARACTER only list upper case alphabetic characters, e.g.,
  • Constraint: CHECK='N'.
In practice, all routines with CHARACTER arguments will permit the use of lower case characters.
Occasionally, an enhancement of an existing routine at a given Mark may weaken some constraints on some arguments, this will not change the behaviour of existing code that calls the routine, but will allow new code to take advantage of enhanced functionality.
The phrase ‘Suggested value:’ introduces a suggestion for a reasonable initial setting for an Input argument (e.g., accuracy or maximum number of iterations) in case you are unsure what value to use; you should be prepared to use a different setting if the suggested value turns out to be unsuitable for your problem.

4.3.3 Array Arguments

Most array arguments have dimensions which depend on the size of the problem. In Fortran terminology they have ‘adjustable dimensions’: the dimensions occurring in their declarations are integer variables which are also arguments of the Library routine.
For example, a Library routine might have the specification:
SUBROUTINE <name> (M, N, A, B, LDB)
INTEGER            M, N, A(N), B(LDB,N), LDB
For a one-dimensional array argument, such as A in this example, the specification would begin
  • A(N) – INTEGER array
You must ensure that the dimension of the array, as declared in your calling (sub)program, is at least as large as the value you supply for N. It may be larger, but the routine uses only the first N elements.
For a two-dimensional array argument, such as B in the example, the specification might be
  • B(LDB,N) – INTEGER array
  • On entry: the m by n matrix B.
and the argument LDB might be described as follows:
  • LDB – INTEGER
  • On entry: the first dimension of the array B as declared in the (sub)program from which <name> is called.
  • Constraint: LDB ≥ M.
You must supply the first dimension of the array B, as declared in your calling (sub)program, through the argument LDB, even though the number of rows actually used by the routine is determined by the argument M. You must ensure that the first dimension of the array is at least as large as the value you supply for M. The extra argument LDB is needed to allow the routine to act on subarrays of a larger two-dimensional array, e.g., factorizing a diagonal submatrix of a larger matrix.
You must also ensure that the second dimension of the array, as declared in your calling (sub)program, is at least as large as the value you supply for N. It may be larger, but the routine uses only the first N columns.
A program to call the hypothetical routine used as an example in this section might include the statements:
INTEGER AA(100), BB(100,50)
LDB = 100
.
.
.
M = 80
N = 20
CALL <name>(M,N,AA,BB,LDB)
or
INTEGER ALLOCATABLE :: AA(:), BB(:,:)
INTEGER             :: M, N, LDB
.
.
.
READ(5,*) M, N
LDB = M
ALLOCATE (AA(M),BB(LDB,N))
CALL <name>(M,N,AA,BB,LDB)
Many NAG routines contain array arguments declared with the ‘assumed size’ array dimension, and would be given as
INTEGER        A(*), B(LDB,*)
However, the original declaration of an array in your calling program must always have dimensions, greater than or equal to the minimum value documented. The advantage of using allocatable arrays is that they can be dynamically allocated to be of a correct size not known at compile time.
Consult an expert or a textbook on Fortran if you have difficulty in calling NAG routines with array arguments.

4.4 Implementation-dependent Information

In order to support all implementations of the Library, the Manual has adopted a convention of using bold italics to distinguish terms which have different interpretations in different implementations.
One bold italicised term is machine precision, which denotes the relative precision to which real floating-point numbers are stored in the computer, e.g., in an implementation with approximately 16 decimal digits of precision, machine precision has a value of approximately 10-16.
The precise value of machine precision is given by the routine X02AJF. Other routines in Chapter X02 return the values of other implementation-dependent constants, such as the overflow threshold, or the largest representable integer. Refer to the X02 Chapter Introduction for more details.
The bold italicised term block size is used only in Chapters F07 and F08. It denotes the block size used by block algorithms in these chapters. You only need to be aware of its value when it affects the amount of workspace to be supplied – see the arguments WORK and LWORK of the relevant routine documents and the appropriate Chapter Introduction.
For each implementation of the Library, a separate Users' Note is published. This is a short document, revised at each mark. At most installations it is available in machine-readable form. It gives any necessary additional information which applies specifically to that implementation, in particular:
  • the values returned by Chapter X02 routines;
  • the default unit numbers for output (see Section 3.5);
  • the meanings of the precision arguments nag_rp (reduced precision), nag_wp (basic precision) and nag_hp (additional precision).

4.5 Example Programs and Results

The example program in Section 10 of most routine documents illustrates a simple call of the routine. The programs are designed so that they can be fairly easily modified, and so serve as the basis for a simple program to solve your problem.
For each implementation of the Library, NAG distributes the example programs in machine-readable form, with all necessary modifications already applied. Many sites make the programs accessible to you in this form. Generic forms of the programs, without implementation-specific modifications, may be obtained directly from the NAG web site. The Users' Note for your implementation will mention any special changes which need to be made to the example programs.
Note that the results obtained from running the example programs may not be identical in all implementations and may not agree exactly with the results in the Manual.
For many routine documents, a plot of the example program results is also provided. In some cases the example program has been modified slightly to produce larger sets of results to give a more representative plot of the solution profile produced.

4.6 Online Documentation

The complete NAG Library Manual, Mark 26 can be viewed online in the following formats:
  • HTML, a fully linked version of the manual using HTML, SVG and MathML (recommended for browsing) and providing links to the PDF version of each document (recommended for printing);
  • PDF, a full PDF manual browsed using the PDF bookmarks, or via HTML index files;
  • Single file PDF, the manual as a single PDF file;
  • Windows HTML help, Windows HTML help version as a single file.
The two single file formats are more compact than the formats that use one file per routine and, for example, allow text searches across the entire manual, but of course the larger files may not be so convenient if you only need to view the documentation for a few routines.
The following sections describe how to obtain the software required to view the documentation and advises you how best to navigate the files with or without a browser.

4.6.1 HTML Format

4.6.1.1 Viewing HTML5 Files
These files do not use any proprietary browser specific features, and conform to relevant W3C Recommendations (HTML, MathML, SVG, CSS).
Support for these languages may require that your browser be updated and/or the installation of additional fonts. This information is restricted to the more widely used browsers. If you require information for additional browsers please contact NAG.
4.6.1.2 Firefox (and other Mozilla based browsers)
Versions of Firefox from Firefox 4 onwards should display MathML in HTML files by default.
Rendering of the mathematics is improved if you install the STIX or other OpenType math fonts if they are not already included on your system (as is the case with OS X and some Linux distributions). Full details of the installers available for these fonts on all the major platforms are included in the Firefox MathML fonts page:
http://www.mozilla.org/projects/mathml/fonts/
4.6.1.3 Other Browsers
If Firefox is not being used, then the javascript on the page loads the MathJax javascript library (http://www.mathjax.org) to enable MathML rendering. By default this is loaded from the web using the MathJax Content Distribution Network. If you require the documentation to work without an Internet connection then you may either use Firefox as described in the previous section or you may download a local copy of MathJax (http://docs.mathjax.org/en/latest/installation.html) which needs to be unpacked on to your local fileserver or file system, and then edit the file ../styles/nagmathml.js changing the line http://cdn.mathjax.org/mathjax/latest/ to refer to your local installation.
4.6.1.4 Navigating HTML5 Files
A main index file has been provided (html/frontmatter/manconts.html) which links to individual Chapter Contents documents, which in turn link to a complete set of HTML files. Use your browser to navigate from this main index file. For each routine document in HTML format you are provided with a link to its equivalent PDF file, this file has been provided primarily for printing purposes.
Each library document contains a number of hyperlinks to particular elements, e.g., arguments, sections, chapter contents, etc. The following key identifies the colour used for each element:
CSS colour | CSS name
black | NAG type
green | appendix, chap, chapter introduction, decision tree, general introduction, section
grey | withdrawn document
pale blue | equation, figure, item in a list, note, bibliographic reference, table, url, verbatim item, website
navy blue | ifail value
red | parameter name
pink | member
purple | optional parameter
royal blue | html table of contents, example plot, routine document, link to a routine example from a table of contents
4.6.1.5 Printing HTML5 Files
It is possible to print your HTML5 files from the browser, however support for printing from browsers, especially support for printing mathematics, varies considerably between versions of browsers and platforms and printer drivers in use. You are recommended to use the PDF version of the document for printing and suitable links are provided at the top and bottom of the HTML document.
4.6.1.6 Windows HTML Help
The Windows HTML Help version of the manual is essentially a compressed version of the HTML5 help, customised for the Windows HTML Help viewer (with a bundled copy of MathJax). This format can be very convenient as it is a small compressed single file version allowing full text search over the entire library. You may find this useful if you have a Microsoft Windows desktop, even if you have the NAG Library installed on a different platform.

4.6.2 PDF Format

4.6.2.1 Viewing and Printing PDF Files
If you do not already have a copy of Adobe Acrobat Reader, a free copy can be downloaded from http://www.adobe.com/reader. Please check this site for availability of a reader for your platform. While we recommend the use of Acrobat Reader, there are alternative PDF viewers available which can also be used, such as xpdf or ghostview.
If Acrobat is not running as a plug-in then the bookmark links will not work correctly if you are browsing the PDF files via http rather than the local filesystem. You are advised to reinstall Adobe Acrobat which should rectify the problem.
We recommend that you use the PDF format when printing library documentation.
4.6.2.2 Navigating the PDF Files
The manual is supplied as a set of individual PDF files, one for each routine document, chapter introduction, etc.. Each PDF file contains bookmarks that can be used to navigate between the files. Alternatively, and often more conveniently, HTML tables of contents are supplied which allow you to navigate to the desired file using a browser, and then using Acrobat as a browser plugin to read or print the document.
Alternatively the single file version of the PDF may be used. In this case the bookmarks will provide links to every routine in the Library, and text search may be used to search the entire Library contents.

5 NAG Library Design and Development

Various aspects of the design and development of the NAG Library, and NAG's technical policies and organization are given in Ford (1982), Ford et al. (1979), Ford and Pool (1984), and Hague et al. (1982).

6 NAG Library Standards

NAG Library development adheres to a number of international standards, see ISO Fortran 95 (1997), ANSI (1966), ANSI (1978), ANSI/IEEE POSIX (1995), Basic Linear Algebra Subprograms Technical (BLAST) Forum (2001).

7 References

ACM (1960–1976) Collected algorithms from ACM index by subject to algorithms
Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug
ANSI (1966) USA standard Fortran Publication X3.9 American National Standards Institute
ANSI (1978) American National Standard Fortran Publication X3.9 American National Standards Institute
ANSI/IEEE (1985) IEEE standard for binary floating-point arithmetic Std 754-1985 IEEE, New York
ANSI/IEEE POSIX (1995) POSIX Standard Thread Library ANSI/IEEE POSIX 1003.1c:1995
Basic Linear Algebra Subprograms Technical (BLAST) Forum (2001) Basic Linear Algebra Subprograms Technical (BLAST) Forum Standard University of Tennessee, Knoxville, Tennessee http://www.netlib.org/blas/blast-forum/blas-report.pdf
Blackford L S, Demmel J, Dongarra J J, Duff I S, Hammarling S, Henry G, Heroux M, Kaufman L, Lumsdaine A, Petitet A, Pozo R, Remington K and Whaley R C (2002) An updated set of Basic Linear Algebra Subprograms (BLAS) ACM Trans. Math. Software 28 135–151
Dongarra J J, Du Croz J J, Duff I S and Hammarling S (1990) A set of Level 3 basic linear algebra subprograms ACM Trans. Math. Software 16 1–28
Dongarra J J, Du Croz J J, Hammarling S and Hanson R J (1988) An extended set of FORTRAN basic linear algebra subprograms ACM Trans. Math. Software 14 1–32
Ford B (1982) Transportable numerical software Lecture Notes in Computer Science 142 128–140 Springer–Verlag
Ford B, Bentley J, Du Croz J J and Hague S J (1979) The NAG Library ‘machine’ Softw. Pract. Exper. 9(1) 65–72
Ford B and Pool J C T (1984) The evolving NAG Library service Sources and Development of Mathematical Software (ed W Cowell) 375–397 Prentice–Hall
Hague S J, Nugent S M and Ford B (1982) Computer-based documentation for the NAG Library Lecture Notes in Computer Science 142 91–127 Springer–Verlag
ISO Fortran 95 (1997) ISO Fortran 95 programming language (ISO/IEC 1539–1:1997)
OpenMP The OpenMP Specification for Parallel Programming http://www.openmp.org
The BLAS Technical Forum Standard (2001) http://www.netlib.org/blas/blast-forum
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


Support from NAG : NAG Library, Mark 26

NAG Library

Support from NAG

▸▿ Contents

1 NAG Technical Support Service
2 NAG Web Site

1 NAG Technical Support Service

The NAG Technical Support Service is available for general enquiries from all users and also for technical queries from sites that subscribe to the support service.
Please see the Users' Note or NAG Technical Support Service for contact details.

2 NAG Web Site

The NAG web site 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 documentation, case studies, industry articles and technical reports. The NAG web site can be accessed via:
  • NAG UK
  • NAG North America
  • NAG Japan
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


Please use the help viewer search for this help file version.


Mark 26 NAG Fortran Library News : NAG Library, Mark 26

NAG Library

Mark 26 NAG Fortran Library News

▸▿ Contents

1 Introduction
2 New Routines
3 Internal Changes Affecting Users
4 Withdrawn Routines
5 Routines Scheduled for Withdrawal

1 Introduction

At Mark 26 of the NAG Library new functionality has been introduced in addition to improvements in existing areas. The Library now contains 1855 user-callable routines, all of which are documented, of which 37 are new at this mark.
Chapter D01 (Quadrature) has two new routines to calculate weights and abscissae for use in Gaussian quadrature and a new routine to solve a specific Gaussian quadrature problem.
Chapter D02 (Ordinary Differential Equations) has reverse communication versions of the Runge–Kutta step and interpolation routines. The interpolation routine has extended the functionality to include the high-order method.
Chapter E04 (Minimizing or Maximizing a Function) has a new suite of routines, NAG Modelling Optimization Suite for quadratic programming (QP), linear semidefinite programming (SDP), semidefinite programming with bilinear matrix inequalities (BMI-SDP), and general nonlinear programming (NLP). This suite can, for example, solve the nearest correlation matrix problem with individually weighted elements or minimize the maximum eigenvalue of a matrix. The suite introduces a novel interface, allowing the gradual build up of a problem definition and avoiding the long parameter lists of earlier interfaces. The SDP solver is based upon a generalized augmented Lagrangian method and as such complements existing solvers in the optimization chapters. The QP/NLP solver of this suite is based upon IPOPT, an interior-point method optimization package, suitable for large-scale problems, that complements the active-set sequential quadratic programming (SQP) solvers already present.
Chapter F08 (Least Squares and Eigenvalue Problems (LAPACK)) has additional blocked (BLAS-3) variants of routines for computing the generalized SVD, or generalized eigenvalues of real or complex matrix pairs.
Chapter G02 (Correlation and Regression Analysis) has another nearest correlation routine.
Chapter X06 (OpenMP Utilities has a new routine to identify, at runtime, whether you are using a threaded Library or not.
At this release we have made changes to the introductory documentation supporting the Library. The document previously called the 'Essential Introduction' has been revised so that relevant information and advice on how to use the Library and its documentation can be found quickly. The document has been renamed to How to Use the NAG Library and its Documentation.
We have also provided clarification of the term 'Direct and Reverse Communication Routines', see Section 3.3.3 in How to Use the NAG Library and its Documentation, and taken the decision to document a number of error conditions, i.e., Dynamic Memory Allocation, License Management and Unexpected Errors (see Sections 3.7, 3.8 and 3.9 in How to Use the NAG Library and its Documentation).
You will also notice that on every HTML page there is now a Keyword Search box.

2 New Routines

The 37 new user-callable routines included in the NAG Library at Mark 26 are as follows.
Routine Name | Purpose
D01TDF | Calculation of weights and abscissae for Gaussian quadrature rules, method of Golub and Welsch
D01TEF | Generates recursion coefficients needed by D01TDF to calculate a Gaussian quadrature rule
D01UBF | Non-automatic routine to evaluate ∫0∞exp-x 2 f x dx
D02PGF | Ordinary differential equations, initial value problem, Runge–Kutta method, integration by reverse communication
D02PHF | Set up interpolant by reverse communication for solution and derivative evaluations at points within the range of the last integration step taken by D02PGF
D02PJF | Evaluate interpolant, set up using D02PQF, to approximate solution and/or solution derivatives at a point within the range of the last integration step taken by D02PGF
E04MWF | Write MPS data file defining LP, QP, MILP or MIQP problem
E04RAF | Initialization of a handle for the NAG optimization modelling suite for problems, such as, quadratic programming (QP), nonlinear programming (NLP), linear semidefinite programming (SDP) or SDP with bilinear matrix inequalities (BMI-SDP)
E04RDF | A reader of sparse SDPA data files for linear SDP problems
E04REF | Define a linear objective function to a problem initialized by E04RAF
E04RFF | Define a linear or a quadratic objective function to a problem initialized by E04RAF
E04RGF | Define a nonlinear objective function to a problem initialized by E04RAF
E04RHF | Define bounds of variables of a problem initialized by E04RAF
E04RJF | Define a block of linear constraints to a problem initialized by E04RAF
E04RKF | Define a block of nonlinear constraints to a problem initialized by E04RAF
E04RLF | Define a structure of Hessian of the objective, constraints or the Lagrangian to a problem initialized by E04RAF
E04RNF | Add one or more linear matrix inequality constraints to a problem initialized by E04RAF
E04RPF | Define bilinear matrix terms to a problem initialized by E04RAF
E04RYF | Print information about a problem handle initialized by E04RAF
E04RZF | Destroy the problem handle initialized by E04RAF and deallocate all the memory used
E04STF | Run an interior point solver on a sparse nonlinear programming problem (NLP) initialized by E04RAF and defined by other routines from the suite
E04SVF | Run the Pennon solver on a compatible problem initialized by E04RAF and defined by other routines from the suite, such as, semidefinite programming (SDP) and SDP with bilinear matrix inequalities (BMI)
E04ZMF | Option setting routine for the solvers from the NAG optimization modelling suite
E04ZNF | Option getting routine for the solvers from the NAG optimization modelling suite
E04ZPF | Option setting routine for the solvers from the NAG optimization modelling suite from external file
F08VCF | Computes, using BLAS-3, the generalized singular value decomposition of a real matrix pair
F08VGF | Produces orthogonal matrices, using BLAS-3, that simultaneously reduce the m by n matrix A and the p by n matrix B to upper triangular form
F08VQF | Computes, using BLAS-3, the generalized singular value decomposition of a complex matrix pair
F08VUF | Produces unitary matrices, using BLAS-3, that simultaneously reduce the complex, m by n, matrix A and the complex, p by n, matrix B to upper triangular form
F08WCF | Computes, for a real nonsymmetric matrix pair, using BLAS-3, the generalized eigenvalues, and optionally, the left and/or right generalized eigenvectors
F08WFF | Performs, using BLAS-3, an orthogonal reduction of a pair of real general matrices to generalized upper Hessenberg form
F08WQF | Computes, for a complex nonsymmetric matrix pair, using BLAS-3, the generalized eigenvalues, and optionally, the left and/or right generalized eigenvectors
F08WTF | Performs, using BLAS-3, a unitary reduction of a pair of complex general matrices to generalized upper Hessenberg form
F08XCF | Computes, for a real nonsymmetric matrix pair, using BLAS-3, the generalized eigenvalues, the generalized real Schur form and, optionally, the left and/or right matrices of Schur vectors
F08XQF | Computes, for a complex nonsymmetric matrix pair, using BLAS-3, the generalized eigenvalues, the generalized complex Schur form and, optionally, the left and/or right matrices of Schur vectors
G02APF | Computes a correlation matrix from an approximate one using a specified target matrix
X06XAF | Tests whether a threaded NAG Library is being used

3 Internal Changes Affecting Users

There have been no internal changes at this mark.

4 Withdrawn Routines

The following routines have been withdrawn from the NAG Library at Mark 26. Warning of their withdrawal was included in the NAG Library Manual at Mark 25, together with advice on which routines to use instead. See the document ‘Advice on Replacement Calls for Withdrawn/Superseded Routines’ for more detailed guidance.
Withdrawn Routine | Replacement Routine(s)
C06EAF | C06PAF
C06EBF | C06PAF
C06ECF | C06PCF
C06EKF | C06FKF
C06FRF | C06PSF
C06FUF | C06PUF
C06GBF | No replacement required
C06GCF | No replacement required
C06GQF | No replacement required
C06GSF | No replacement required
C06HAF | C06REF
C06HBF | C06RFF
C06HCF | C06RGF
C06HDF | C06RHF
D01BAF | D01UAF
D01BBF | D01TBF
D02PCF | D02PEF and associated D02P routines
D02PDF | D02PFF or D02PGF and associated D02P routines
D02PVF | D02PQF
D02PWF | D02PRF
D02PXF | D02PSF
D02PYF | D02PTF
D02PZF | D02PUF
F04YCF | F04YDF
F04ZCF | F04ZDF
G01AAF | G01ATF

5 Routines Scheduled for Withdrawal

The routines listed below are scheduled for withdrawal from the NAG Library, because improved routines have now been included in the Library. You are advised to stop using routines which are scheduled for withdrawal and to use recommended replacement routines instead. See the document ‘Advice on Replacement Calls for Withdrawn/Superseded Routines’ for more detailed guidance, including advice on how to change a call to the old routine into a call to its recommended replacement.
The following routines will be withdrawn at Mark 27.
Routines Scheduled for Withdrawal | Replacement Routine(s)
D01RBF | No replacement required
D02TKF | D02TLF
E02ACF | E02ALF
F02SDF | F12AGF and F12FGF
F02WDF | F02WUF and F08AEF (DGEQRF)
G10BAF | G10BBF
The following routines have been superseded, but will not be withdrawn from the Library until Mark 28 at the earliest.
Superseded Routine | Replacement Routine(s)
C06FPF | C06PQF
C06FQF | C06PQF
F04ABF | F07FBF (DPOSVX)
F04AEF | F07ABF (DGESVX)
F04ASF | F07FBF (DPOSVX)
F04ATF | F07ABF (DGESVX)
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


Advice on Replacement Calls for Withdrawn/Superseded Routines : NAG Library, Mark 26

NAG Library

Advice on Replacement Calls for Withdrawn/Superseded Routines

The following list gives the names of routines that are suitable replacements for routines that have either been withdrawn or superseded since Mark 19.
The list indicates the minimum change necessary, but many of the replacement routines have additional flexibility and you may wish to take advantage of new features. It is strongly recommended that you consult the routine documents.

▸▿ Contents

▸▿ C05 – Roots of One or More Transcendental Equations
C05ADF
C05AGF
C05AJF
C05NBF
C05NCF
C05NDF
C05PBF/C05PBA
C05PCF/C05PCA
C05PDF/C05PDA
C05ZAF
▸▿ C06 – Summation of Series
C06DBF
C06EAF
C06EBF
C06ECF
C06EKF
C06FPF
C06FQF
C06FRF
C06FUF
C06GBF
C06GCF
C06GQF
C06GSF
C06HAF
C06HBF
C06HCF
C06HDF
▸▿ D01 – Quadrature
D01BAF
D01BBF
D01RBF
▸▿ D02 – Ordinary Differential Equations
D02PCF
D02PDF
D02PVF
D02PWF
D02PXF
D02PYF
D02PZF
D02TKF
▸▿ E01 – Interpolation
E01SEF
E01SFF
▸▿ E02 – Curve and Surface Fitting
E02ACF
▸▿ E04 – Minimizing or Maximizing a Function
E04CCF/E04CCA
E04FDF
E04GCF
E04GEF
E04HFF
E04JAF
E04KAF
E04KCF
E04LAF
E04UNF
E04UPF
E04ZCF/E04ZCA
▸▿ F01 – Matrix Operations, Including Inversion
F01MAF
▸▿ F02 – Eigenvalues and Eigenvectors
F02BBF
F02BCF
F02BDF
F02BJF
F02EAF
F02EBF
F02FAF
F02FCF
F02FDF
F02FHF
F02GAF
F02GBF
F02GJF
F02HAF
F02HCF
F02HDF
F02SDF
F02WDF
F02WEF
F02XEF
▸▿ F03 – Determinants
F03AAF
F03ABF
F03ACF
F03ADF
F03AEF
F03AFF
▸▿ F04 – Simultaneous Linear Equations
F04AAF
F04ABF
F04ACF
F04ADF
F04AEF
F04AFF
F04AGF
F04AHF
F04AJF
F04ARF
F04ASF
F04ATF
F04EAF
F04FAF
F04JAF
F04JDF
F04JLF
F04JMF
F04KLF
F04KMF
F04MAF
F04MBF
F04YCF
F04ZCF
▸▿ F11 – Large Scale Linear Systems
F11BAF
F11BBF
F11BCF
F11GAF
F11GBF
F11GCF
▸▿ G01 – Simple Calculations on Statistical Data
G01AAF
▸▿ G05 – Random Number Generators
G05CAF
G05CBF
G05CCF
G05CFF
G05CGF
G05DAF
G05DBF
G05DCF
G05DDF
G05DEF
G05DFF
G05DHF
G05DJF
G05DKF
G05DPF
G05DRF
G05DYF
G05DZF
G05EAF
G05EBF
G05ECF
G05EDF
G05EEF
G05EFF
G05EGF
G05EHF
G05EJF
G05EWF
G05EXF
G05EYF
G05EZF
G05FAF
G05FBF
G05FDF
G05FEF
G05FFF
G05FSF
G05GAF
G05GBF
G05HDF
G05HKF
G05HLF
G05HMF
G05HNF
G05KAF
G05KBF
G05KCF
G05KEF
G05LAF
G05LBF
G05LCF
G05LDF
G05LEF
G05LFF
G05LGF
G05LHF
G05LJF
G05LKF
G05LLF
G05LMF
G05LNF
G05LPF
G05LQF
G05LXF
G05LYF
G05LZF
G05MAF
G05MBF
G05MCF
G05MDF
G05MEF
G05MJF
G05MKF
G05MLF
G05MRF
G05MZF
G05NAF
G05NBF
G05PAF
G05PCF
G05QAF
G05QBF
G05QDF
G05RAF
G05RBF
G05YAF
G05YBF
G05YCF
G05YDF
G05YEF
G05YFF
G05YGF
G05YHF
G05ZAF
▸▿ G10 – Smoothing in Statistics
G10BAF
▸▿ G13 – Time Series Analysis
G13DCF
▸▿ P01 – Error Trapping
P01ABF
▸▿ X02 – Machine Constants
X02DAF
X02DJF

C05 – Roots of One or More Transcendental Equations

C05ADF

Withdrawn at Mark 25.
Replaced by C05AYF.
Old: FUNCTION F(XX)
        ...
     END FUNCTION F
     ...
     CALL C05ADF(A,B,EPS,ETA,F,X,IFAIL)
New: FUNCTION F(XX,IUSER,RUSER)
        ...
        INTEGER,            INTENT(INOUT) :: IUSER(*)
        REAL (KIND=nag_wp), INTENT(INOUT) :: RUSER(*)
        ...
     END FUNCTION F
     ...
     INTEGER            :: IUSER(1)
     REAL (KIND=nag_wp) :: RUSER(1)
     ...
     CALL C05AYF(A,B,EPS,ETA,F,X,IUSER,RUSER,IFAIL)

C05AGF

Withdrawn at Mark 25.
Replaced by C05AUF.
Old: FUNCTION F(XX)
        ...
     END FUNCTION F
     ...
     CALL C05AGF(X,H,EPS,ETA,F,A,B,IFAIL)
New: FUNCTION F(XX,IUSER,RUSER)
        ...
        INTEGER,            INTENT(INOUT) :: IUSER(*)
        REAL (KIND=nag_wp), INTENT(INOUT) :: RUSER(*)
        ...
     END FUNCTION F
     ...
     INTEGER            :: IUSER(1)
     REAL (KIND=nag_wp) :: RUSER(1)
     ...
     CALL C05AUF(X,H,EPS,ETA,F,A,B,IUSER,RUSER,IFAIL)

C05AJF

Withdrawn at Mark 25.
Replaced by C05AWF.
Old: FUNCTION F(XX)
        ...
     END FUNCTION F
     ...
     CALL C05AJF(X,EPS,ETA,F,NFMAX,IFAIL)
New: FUNCTION F(XX,IUSER,RUSER)
        ...
        INTEGER,            INTENT(INOUT) :: IUSER(*)
        REAL (KIND=nag_wp), INTENT(INOUT) :: RUSER(*)
        ...
     END FUNCTION F
     ...
     INTEGER            :: IUSER(1)
     REAL (KIND=nag_wp) :: RUSER(1)
     ...
     CALL C05AWF(X,EPS,ETA,F,NFMAX,IUSER,RUSER,IFAIL)

C05NBF

Withdrawn at Mark 25.
Replaced by C05QBF.
Old: SUBROUTINE FCN(N,X,FVEC,IFLAG)
        ...
     END SUBROUTINE FCN
     ...
     CALL C05NBF(FCN,N,X,FVEC,XTOL,WA,LWA,IFAIL)
New: SUBROUTINE FCN(N,X,FVEC,IUSER,RUSER,IFLAG)
        ...
        INTEGER,            INTENT(INOUT) :: IUSER(*)
        REAL (KIND=nag_wp), INTENT(INOUT) :: RUSER(*)
        ...
     END FUNCTION FCN
     ...
     INTEGER            :: IUSER(1)
     REAL (KIND=nag_wp) :: RUSER(1)
     ...
     CALL C05QBF(FCN,N,X,FVEC,XTOL,IUSER,RUSER,IFAIL)

C05NCF

Withdrawn at Mark 25.
Replaced by C05QCF.
Old: SUBROUTINE FCN(N,X,FVEC,IFLAG)
        ...
     END SUBROUTINE FCN
     ...
     REAL (KIND=nag_wp) :: FJAC(LDFJAC,N)
     ...
     CALL C05NCF(FCN,N,X,FVEC,XTOL,MAXFEV,ML,MU,EPSFCN,DIAG,MODE,FACTOR, &
                 NPRINT,NFEV,FJAC,LDFJAC,R,LR,QTF,W,IFAIL)
New: SUBROUTINE FCN(N,X,FVEC,IUSER,RUSER,IFLAG)
        ...
        INTEGER,            INTENT(INOUT) :: IUSER(*)
        REAL (KIND=nag_wp), INTENT(INOUT) :: RUSER(*)
        ...
     END FUNCTION FCN
     ...
     INTEGER            :: IUSER(1)
     REAL (KIND=nag_wp) :: FJAC(N,N), RUSER(1)
     ...
     CALL C05QCF(FCN,N,X,FVEC,XTOL,MAXFEV,ML,MU,EPSFCN,MODE,DIAG,FACTOR, &
                 NPRINT,NFEV,FJAC,R,QTF,IUSER,RUSER,IFAIL)

C05NDF

Withdrawn at Mark 25.
Replaced by C05QDF.
Old: REAL (KIND=nag_wp) :: FJAC(LDFJAC,N)
     ...
     CALL C05NDF(IREVCM,N,X,FVEC,XTOL,ML,MU,EPSFCN,DIAG,MODE,FACTOR, &
                 FJAC,LDFJAC,R,LR,QTF,W,IFAIL)
New: REAL (KIND=nag_wp) :: FJAC(N,N), RWSAV(4*N+20)
     INTEGER            :: IWSAV(17)
     ...
     CALL C05QDF(IREVCM,N,X,FVEC,XTOL,ML,MU,EPSFCN,MODE,DIAG,FACTOR, &
                 FJAC,R,QTF,IWSAV,RWSAV,IFAIL)

C05PBF/C05PBA

Withdrawn at Mark 25.
Replaced by C05RBF.
Old: SUBROUTINE FCN_C05PBF(N,X,FVEC,FJAC,LDFJAC,IFLAG)
        ...
     END SUBROUTINE FCN_C05PBF
     ...
     REAL (KIND=nag_wp) :: FJAC(LDFJAC,N)
     ...
     CALL C05PBF(FCN_C05PBF,N,X,FVEC,FJAC,LDFJAC,XTOL,WA,LWA,IFAIL)
        or
     SUBROUTINE FCN_C05PBA(N,X,FVEC,FJAC,LDFJAC,IFLAG,IUSER,RUSER)
        ...
     END SUBROUTINE FCN_C05PBA
     ...
     REAL (KIND=nag_wp) :: FJAC(LDFJAC,N)
     ...
     CALL C05PBA(FCN_C05PBA,N,X,FVEC,FJAC,LDFJAC,XTOL,WA,LWA,IUSER,RUSER,IFAIL)
New: SUBROUTINE FCN(N,X,FVEC,FJAC,IUSER,RUSER,IFLAG)
        ...
     END SUBROUTINE FCN
     ...
     REAL (KIND=nag_wp) :: FJAC(N,N)
     ...
     CALL C05RBF(FCN,N,X,FVEC,FJAC,XTOL,IUSER,RUSER,IFAIL)

C05PCF/C05PCA

Withdrawn at Mark 25.
Replaced by C05RCF.
Old: SUBROUTINE FCN_C05PCF(N,X,FVEC,FJAC,LDFJAC,IFLAG)
        ...
     END SUBROUTINE FCN_C05PCF
     ...
     REAL (KIND=nag_wp) :: FJAC(LDFJAC,N)
     ...
     CALL C05PCF(FCN_C05PCF,N,X,FVEC,FJAC,LDFJAC,XTOL,MAXFEV,DIAG,MODE,FACTOR, &
                 NPRINT,NFEV,NJEV,R,LR,QTF,W,IFAIL)
        or
     SUBROUTINE FCN_C05PCA(N,X,FVEC,FJAC,LDFJAC,IFLAG,IUSER,RUSER)
        ...
     END SUBROUTINE FCN_C05PCA
     ...
     REAL (KIND=nag_wp) :: FJAC(LDFJAC,N)
     ...
     CALL C05PCA(FCN_C05PCA,N,X,FVEC,FJAC,LDFJAC,XTOL,MAXFEV,DIAG,MODE,FACTOR, &
                 NPRINT,NFEV,NJEV,R,LR,QTF,W,IUSER,RUSER,IFAIL)
New: SUBROUTINE FCN(N,X,FVEC,FJAC,IUSER,RUSER,IFLAG)
        ...
        INTEGER,            INTENT(INOUT) :: IUSER(*)
        REAL (KIND=nag_wp), INTENT(INOUT) :: RUSER(*)
        ...
     END FUNCTION FCN
     ...
     REAL (KIND=nag_wp) :: FJAC(N,N)
     ...
     CALL C05RCF(FCN,N,X,FVEC,FJAC,XTOL,MAXFEV,MODE,DIAG,FACTOR, &
                 NPRINT,NFEV,NJEV,R,QTF,IUSER,RUSER,IFAIL)

C05PDF/C05PDA

Withdrawn at Mark 25.
Replaced by C05RDF.
Old: REAL (KIND=nag_wp) :: FJAC(LDFJAC,N), RWSAV(10)
     INTEGER            :: IWSAV(15)
     ...
     CALL C05PDF(IREVCM,N,X,FVEC,FJAC,LDFJAC,XTOL,DIAG,MODE,FACTOR, &
                 R,LR,QTF,W,IFAIL)
        or
     CALL C05PDA(IREVCM,N,X,FVEC,FJAC,LDFJAC,XTOL,DIAG,MODE,FACTOR, &
                 R,LR,QTF,W,LWSAV,IWSAV,RWSAV,IFAIL)
New: REAL (KIND=nag_wp) :: FJAC(N,N), RWSAV(4*N+10)
     INTEGER            :: IWSAV(17)
     ...
     CALL C05RDF(IREVCM,N,X,FVEC,FJAC,XTOL,MODE,DIAG,FACTOR,        &
                 R,QTF,IWSAV,RWSAV,IFAIL)

C05ZAF

Withdrawn at Mark 25.
Replaced by C05ZDF.
Old: CALL C05ZAF(M,N,X,FVEC,FJAC,LDFJAC,XP,FVECP,MODE,ERR)
New: IFAIL = 0
     CALL C05ZDF(MODE,M,N,X,FVEC,FJAC,LDFJAC,XP,FVECP,ERR,IFAIL)
The array XP must now have dimension N regardless of the value of MODE, and likewise ERR must now have dimension M regardless. The argument IFAIL is the standard NAG argument for error trapping. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.

C06 – Summation of Series

C06DBF

Withdrawn at Mark 25.
Replaced by C06DCF.
Old: DO I = 1, LX
        RES(I) = C06DBF(X(I),C,N,S)
     END DO
New: XMIN = -1.0D0
     XMAX = 1.0D0

     SELECT CASE (S)
     CASE (1,2,3)
        S_USE = S
     CASE DEFAULT
        S_USE = 2
     END SELECT

     IFAIL = 0
     CALL C06DCF(X,LX,XMIN,XMAX,C,N,S_USE,RES,IFAIL)
The old routine C06DBF returns a single sum at a time, whereas the new routine C06DCF returns a vector of LX values at once. The values supplied in X to C06DCF are un-normalized original variable values in the range XMIN,XMAX. The argument IFAIL is the standard NAG argument for error trapping. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.

C06EAF

Withdrawn at Mark 26.
Replaced by C06PAF.
C06PAF removes restrictions on sequence length and combines transform directions.
Old: CALL C06EAF(X,N,IFAIL)
New: CALL C06PAF('F',X,N,WORK,IFAIL)
where WORK is a real array of length 3×N+100 and the dimension of the array X has been extended from the original N to N+2. The output values X are stored in a different order with real and imaginary parts stored contiguously. The mapping of output elements is as follows:
  • X 2×i ← X i, for i=0,1,…,N/2 and
    X 2×i+1 ← X N-i , for i=1,2,…,N+1/2.

C06EBF

Withdrawn at Mark 26.
Replaced by C06PAF.
C06PAF removes restrictions on sequence length and combines transform directions.
Old: CALL C06EBF(X,N,IFAIL)
New: CALL C06PAF('B',X,N,WORK,IFAIL)
where WORK is a real array of length 3×N+100 and the dimension of the array X has been extended from the original N to N+2. The input values of X are stored in a different order with real and imaginary parts stored contiguously. Also C06PAF performs the inverse transform without the need to first conjugate. If prior conjugation of original array X is assumed then the mapping of input elements is:
  • X 2×i←X i, for i=0,1,…,N/2 and
    X 2×i+1←X N-i, for i=1,2,…,N-1/2.

C06ECF

Withdrawn at Mark 26.
Replaced by C06PCF.
C06PCF removes restrictions on sequence length, combines transform directions and uses complex types.
Old: CALL C06ECF(X,Y,N,IFAIL)
New: CALL C06PCF('F',Z,N,WORK,IFAIL)
where WORK is a complex array of length 2×N+15 and Z is a complex array of length N such that Z i=CMPLX X i,Y i , for i=0,1,…N-1 on input and output.

C06EKF

Withdrawn at Mark 26.
Replaced by C06FKF.
C06FKF removes restrictions on sequence length.
Old: CALL C06EKF(IJOB,X,Y,N,IFAIL)
New: CALL C06FKF(IJOB,X,Y,N,WORK,IFAIL)
where WORK is a real array of length N.

C06FPF

Scheduled for withdrawal at Mark 28.
Replaced by C06PQF.
C06PQF provides a simpler interface for both forward and backward transforms.
Old: CALL C06FPF(M,N,X,INIT,TRIG,WORK,IFAIL)
New: CALL C06PQF('F',N,M,X,WORK,IFAIL)
where the dimension of WORK has been extended from M×N to M×N+2×N (to include TRIG) and the dimension of the array X has been extended from the original N×M to N+2×M. The input values are stored stored slightly differently to allow for two extra storage spaces at the end of each sequence.
The mapping of input elements is as follows:
  • for j=1,2,…,M
    • J 1=j-1×N; J 2=j-1×N+2;
    • X J 2+2×i←X J 1+i, for i=0,1,…,N;
    • X J 2+N and X J 2+N+1 need not be set.
The output values X are stored in a different order with real and imaginary parts of each Hermitian sequence stored contiguously.
The mapping of output elements is as follows:
(Here X begins at element zero X 0.)
For j=1,2,…,M
  • J 1=j-1×N; J 2=j-1×N+2;
  • X J 2+2×i←X J 1+i, for i=0,1,…,N/2 [real parts];
  • X J 2+2×i+1←X J 1+N-i, for i=1,2,…,N+1/2 [imaginary parts];
  • X J 2+1 is set to zero;
  • X J 2+N+1 is set to zero when N is even.

C06FQF

Scheduled for withdrawal at Mark 28.
Replaced by C06PQF.
C06PQF provides a simpler interface for both forward and backward transforms.
Old: CALL C06FQF(M,N,X,INIT,TRIG,WORK,IFAIL)
New: CALL C06PQF('B',N,M,X,WORK,IFAIL)
where the dimension of WORK has been extended from M×N to M×N+2×N (to include TRIG) and the dimension of the array X has been extended from the original N×M to N+2×M.
The input values X are stored in a different order with real and imaginary parts of each Hermitian sequence stored contiguously.
The mapping of input elements is as follows:
(Here X begins at element zero X 0.)
For j=1,2,…,M
  • J 1=j-1×N; J 2=j-1×N+2;
  • X J 2+2×i←X J 1+i, for i=0,1,…,N/2 [real parts];
  • X J 2+2×i+1 ← X J 1+N-i, for i=1,2,…,N+1/2 [imaginary parts];
  • X J 2+1 must be zero;
  • X J 2+N+1 must zero when N is even.
The output values are stored stored slightly differently to allow for two extra storage spaces at the end of each sequence.
The mapping of output elements is as follows:
For j=1,2,…,M
  • J 1=j-1×N; J 2=j-1×N+2;
  • X J 2+2×i←X J 1+i, for i=0,1,…,N;
  • X J 2+N and X J 2+N+1 will be set to zero.

C06FRF

Withdrawn at Mark 26.
Replaced by C06PSF.
C06PSF provides a simpler interface for both forward and backward transforms.
Old: call C06FRF(M,N,X,Y,INIT,TRIG,WORK,IFAIL)
New: Do j = 1, m*n
         cx(j) = cmplx(x(j),y(j),kind=nag_wp)
     End Do
     Call C06PSF('F',M,N,CX,CWORK,IFAIL)
     x(1:m*n) = real(cx(1:m*n))
     y(1:m*n) = aimag(cx(1:m*n))
where cx and cwork are complex array of length m×n and n×m+2×n+15 respectively.

C06FUF

Withdrawn at Mark 26.
Replaced by C06PUF.
C06PUF provides a simpler interface for both forward and backward transforms.
Old: Call C06FUF(M,N,X,Y,INIT,TRIGM,TRIGN,WORK,IFAIL)
New: Do j = 1, m*n
         cx(j) = cmplx(x(j),y(j),kind=nag_wp)
     End Do
     Call C06PUF('F',M,N,CX,CWORK,IFAIL)
     x(1:m*n) = real(cx(1:m*n))
     y(1:m*n) = aimag(cx(1:m*n))
where cx and cwork are complex arrays of lengths m×n and n×m+2×n+2×m+30 respectively.

C06GBF

Withdrawn at Mark 26.
There is no replacement for this routine.

C06GCF

Withdrawn at Mark 26.
There is no replacement for this routine.

C06GQF

Withdrawn at Mark 26.
There is no replacement for this routine.

C06GSF

Withdrawn at Mark 26.
There is no replacement for this routine.

C06HAF

Withdrawn at Mark 26.
Replaced by C06REF.
C06REF has a simpler interface, storing sequences by column.
Old: Call C06HAF(M,N,X,INIT,TRIG,WORK,IFAIL)
New: Call C06REF(M,N,Y,IFAIL)
where y 1:n-1:m is a two-dimensional real array such that y 1:n-1,j = x j:m×n-1:m .

C06HBF

Withdrawn at Mark 26.
Replaced by C06RFF.
C06RFF has a simpler interface, storing sequences by column.
Old: Call C06HBF(M,N,X,INIT,TRIG,WORK,IFAIL)
New: Call C06RFF(M,N,Y,IFAIL)
where y 0:n:m is a two-dimensional real array such that y 0:n,j = x j:m×n+1:m .

C06HCF

Withdrawn at Mark 26.
Replaced by C06RGF.
C06RGF has a simpler interface, storing sequences by column.
Old: Call C06HCF(DIRECT,M,N,X,INIT,TRIG,WORK,IFAIL)
New: Call C06RGF(IDIR,M,N,Y,IFAIL)
where y 1:n:m is a two-dimensional real array such that y 1:n,j = x j:m×n:m ; IDIR=1 or -1 for forward and inverse transforms respectively.

C06HDF

Withdrawn at Mark 26.
Replaced by C06RHF.
C06RHF has a simpler interface, storing sequences by column.
Old: Call C06HDF(DIRECT,M,N,X,INIT,TRIG,WORK,IFAIL)
New: Call C06RHF(IDIR,M,N,Y,IFAIL)
where y 0:n-1:m is a two-dimensional real array such that y 0:n-1,j = x j:m×n:m ; IDIR=1 or -1 for forward and inverse transforms respectively.

D01 – Quadrature

D01BAF

Withdrawn at Mark 26.
Replaced by D01UAF.
Withdrawn to provide thread safety in passing of data to user supplied function and a simpler interface to select the quadrature rule.
  Old :  FUNCTION FUN(x)

          ...
         real(kind=nag_wp) :: FUN
         real(kind=nag_wp), intent(in) :: X
         FUN = ...
         END FUNCTION

         DINEST = D01BAF(D01XXX,A,B,N,FUN,IFAIL)

  New :  SUBROUTINE F(X,NX,FV,IFLAG,IUSER,RUSER)
           ...
        ! see example below
          ...
         END SUBROUTINE F
          ...
          integer :: key
          integer, allocatable :: iuser(:)
          real(kind=nag_wp), allocatable :: ruser(:)

         ! set KEY according to quadrature formula
         ! KEY =  0 : (D01XXX=D01BAZ)
         ! KEY = -3 : (D01XXX=D01BAY)
         ! KEY = -4 : (D01XXX=D01BAW)
         ! KEY = -5 : (D01XXX=D01BAX)
         ! KEY = ABS(KEY) for normal weights
         KEY = 0

         allocate(iuser(liuser), ruser(lruser))

         CALL D01UAF(KEY,A,B,N,F,DINEST,IUSER,RUSER,IFAIL)
IUSER and RUSER are arrays available to allow you to pass information to the user-supplied subroutine F.
IFLAG is an integer which you may use to force an immediate exit from D01UAF in case of an error in the user-supplied subroutine F.
F may be used to call the original FUN as follows, although it may be more efficient to recode the integrand.
          SUBROUTINE F(X,NX,FV,IFLAG,IUSER,RUSER)
           ...
           integer, intent(in) :: NX
           integer, intent(inout) :: iflag
           real(kind=nag_wp), intent(in) :: X(NX)
           real(kind=nag_wp), intent(out) :: fv(nx)
           real(kind=wp), intent(inout) :: ruser(*)
           integer, intent(inout) :: iuser(*)
           integer :: j
           external FUN

           do j=1,nx
              FV(j)  = FUN(x(j))
           enddo

          END SUBROUTINE F

D01BBF

Withdrawn at Mark 26.
Replaced by D01TBF.
Withdrawn to provide thread safety in passing of data to the user-supplied routine and a simpler interface to select the quadrature rule.
  Old :  CALL D01BBF(D01XXX,A,B,ITYPE,N,WEIGHT,ABSCIS,IFAIL)
  New :  Integer :: key
         CALL D01TBF(KEY,A,B,N,WEIGHT,ABSICS,IFAIL)
The supplied subroutines D01XXX and the argument ITYPE have been combined into a single argument KEY. KEY<0 is equivalent to ITYPE=1 (adjusted weights). KEY>0 is equivalent to ITYPE =0 (normal weights). KEY indicates the quadrature rule.
  • KEY=0 : Gauss–Legendre (D01XXX=D01BAZ)
  • KEY=3 : Gauss–Laguerre (D01XXX=D01BAX)
  • KEY=4 : Gauss–Hermite (D01XXX=D01BAW)
  • KEY=5 : Rational Gauss (D01XXX=D01BAY)

D01RBF

Scheduled for withdrawal at Mark 27.
There is no replacement for this routine.
Withdrawn as a separate diagnostic routine is not required. The details of the computation, as stored in the parameters ICOM and COM, are specified in Section 10.1 in D01RAF.
See Section 10 in D01RAF for further details.

D02 – Ordinary Differential Equations

D02PCF

Withdrawn at Mark 26.
Replaced by D02PEF and associated D02P routines.
These replacements were made primarily for reasons of threadsafety.
Old: CALL D02PVF(N,TSTART,YINIT,TEND,TOL,THRESH,METHOD,'U',ERRASS, &
                 HSTART,W,LW,IFAIL)
     ...
     CALL D02PCF(F,TWANT,T,Y,YP,YMAX,W,IFAIL)

New: IF (.Not. ERRASS) METHOD = -METHOD
     CALL D02PQF(N,TSTART,TEND,YINIT,TOL,THRESH,METHOD,HSTART,IWSAV, &
                 RWSAV,IFAIL)
     ...
     CALL D02PEF(F2,N,TWANT,T,Y,YP,YMAX,IUSER,RUSER,IWSAV,RWSAV,IFAIL)
IWSAV is an integer array of length 130 and RWSAV is a real array of length 350+32×N.
IUSER and RUSER are arrays available to allow you to pass information to the user defined routine F2 (see F in D02PEF).
The definition of F2 (see F in D02PEF) can use the original routine F as follows:
   SUBROUTINE F2(T,N,Y,YP,IUSER,RUSER)
!     .. Scalar Arguments ..
      Real (Kind=wp), Intent (In)      :: t
      Integer, Intent (In)             :: n
!     .. Array Arguments ..
      Real (Kind=wp), Intent (Inout)   :: ruser(1)
      Real (Kind=wp), Intent (In)      :: y(n)
      Real (Kind=wp), Intent (Out)     :: yp(n)
      Integer, Intent (Inout)          :: iuser(1)
!     .. Procedure Arguments ..
      External                         :: f
!     .. Executable Statements ..
      Continue

      Call f(t,y,yp)

      Return
    End Subroutine F2

D02PDF

Withdrawn at Mark 26.
Replaced by D02PFF or D02PGF and associated D02P routines.
These replacements were made primarily for reasons of threadsafety. D02PGF also offers a reverse communication approach.
Old: CALL D02PVF(N,TSTART,YINIT,TEND,TOL,THRESH,METHOD,'U',ERRASS, &
                 HSTART,W,LW,IFAIL)
     ...
     CALL D02PDF(F,T,Y,YP,WORK,IFAIL)

New: IF (.Not. ERRASS) METHOD = -METHOD
     CALL D02PQF(N,TSTART,TEND,YINIT,TOL,THRESH,METHOD,HSTART,IWSAV, &
                 RWSAV,IFAIL)
     ...
     CALL D02PFF(F2,N,T,Y,YP,IUSER,RUSER,IWSAV,RWSAV,IFAIL)
IWSAV is an integer array of length 130 and RWSAV is a real array of length 350+32×N.
IUSER and RUSER are arrays available to allow you to pass information to the user defined routine F2 (see F in D02PEF).
The definition of F2 (see F in D02PEF) can use the original routine F as follows:
   SUBROUTINE F2(T,N,Y,YP,IUSER,RUSER)
!     .. Scalar Arguments ..
      Real (Kind=wp), Intent (In)      :: t
      Integer, Intent (In)             :: n
!     .. Array Arguments ..
      Real (Kind=wp), Intent (Inout)   :: ruser(1)
      Real (Kind=wp), Intent (In)      :: y(n)
      Real (Kind=wp), Intent (Out)     :: yp(n)
      Integer, Intent (Inout)          :: iuser(1)
!     .. Procedure Arguments ..
      External                         :: f
!     .. Executable Statements ..
      Continue

      Call f(t,y,yp)

      Return
    End Subroutine F2

D02PVF

Withdrawn at Mark 26.
Replaced by D02PQF.
This replacement was made primarily for reasons of threadsafety.
See D02PCF and D02PDF for further information.

D02PWF

Withdrawn at Mark 26.
Replaced by D02PRF.
This replacement was made primarily for reasons of threadsafety.
Old: CALL D02PWF(TENDNU,IFAIL)
New: CALL D02PRF(TENDNU,IWSAV,RWSAV,IFAIL)
IWSAV is an integer array of length 130 and RWSAV is a real array of length 350.

D02PXF

Withdrawn at Mark 26.
Replaced by D02PSF.
This replacement was made primarily for reasons of threadsafety.
Old: CALL D02PXF(TWANT,REQEST,NWANT,YWANT,YPWANT,F,WORK,WRKINT, &
                 LENINT,IFAIL)
New:
     If (REQEST=='S' .or. REQEST=='s') Then
       IDERIV = 0
     Else if (REQEST=='D' .or. REQEST=='d') Then
       IDERIV = 1
     Else
       IDERIV = 2
     End If
     CALL D02PSF(TWANT,IDERIV,NWANT,YWANT,YPWANT,F2,WORKINT, &
                 LENINT,IUSER,RUSER,IWSAV,RWSAV,IFAIL)
IWSAV is an integer array of length 130 and RWSAV is a real array of length 350+32×N.
IUSER and RUSER are arrays available to allow you to pass information to the user defined routine F2 (see F in D02PSF).
WCOMM is a real array of length LWCOMM. See the routine document for D02PSF for further information.
The definition of F2 (see F in D02PSF) can use the original routine F as follows:
   SUBROUTINE F2(T,N,Y,YP,IUSER,RUSER)
!     .. Scalar Arguments ..
      Real (Kind=wp), Intent (In)      :: t
      Integer, Intent (In)             :: n
!     .. Array Arguments ..
      Real (Kind=wp), Intent (Inout)   :: ruser(1)
      Real (Kind=wp), Intent (In)      :: y(n)
      Real (Kind=wp), Intent (Out)     :: yp(n)
      Integer, Intent (Inout)          :: iuser(1)
!     .. Procedure Arguments ..
      External                         :: f
!     .. Executable Statements ..
      Continue

      Call f(t,y,yp)

      Return
    End Subroutine F2

D02PYF

Withdrawn at Mark 26.
Replaced by D02PTF.
This replacement was made primarily for reasons of threadsafety.
Old: Call D02PYF(TOTFCN,STPCST,WASTE,STPSOK,HNEXT,IFAIL)
New: Call D02PTF(TOTFCN,STPCST,WASTE,STPSOK,HNEXT,IWSAV, &
                 RWSAV,IFAIL)

D02PZF

Withdrawn at Mark 26.
Replaced by D02PUF.
This replacement was made primarily for reasons of threadsafety.
Old: Call D02PZF(RMSERR,ERRMAX,TERRMX,WORK,IFAIL)
New: Call D02PUF(N,RMSERR,ERRMAX,TERRMX,IWSAV,RWSAV,IFAIL)
N must be unchanged from that passed to D02PQF.
IWSAV is an integer array of length 130 and RWSAV is a real array of length 350+32×N.

D02TKF

Scheduled for withdrawal at Mark 27.
Replaced by D02TLF.
This replacement was made primarily for reasons of threadsafety.
Old: Call D02TKF(FFUN,FJAC,GAFUN,GBFUN,GAJAC,GBJAC,GUESS,RCOMM,ICOMM,IFAIL)
New: Call D02TLF(FFUN,FJAC,GAFUN,GBFUN,GAJAC,GBJAC,GUESS,RCOMM,ICOMM,IUSER, &
                 RUSER,IFAIL)
The arrays IUSER and RUSER are also supplied as an additional two arguments to the seven user-supplied routines. These arrays are free to use to supply information to the seven routine arguments.

E01 – Interpolation

E01SEF

Withdrawn at Mark 20.
Replaced by E01SGF.
Old: CALL E01SEF(M,X,Y,F,RNW,RNQ,NW,NQ,FNODES,MINNQ,WRK,IFAIL)
New: CALL E01SGF(M,X,Y,F,NW,NQ,IQ,LIQ,RQ,LRQ,IFAIL)
E01SEF has been superseded by E01SGF which gives improved accuracy, facilities for obtaining gradient values and a consistent interface with E01TGF for interpolation of scattered data in three dimensions.
The interpolant generated by the two routines will not be identical, but similar results may be obtained by using the same values of NW and NQ. Details of the interpolant are passed to the evaluator through the arrays IQ and RQ rather than FNODES and RNW.

E01SFF

Withdrawn at Mark 20.
Replaced by E01SHF.
Old: CALL E01SFF(M,X,Y,F,RNW,FNODES,PX,PY,PF,IFAIL)
New: CALL E01SHF(M,X,Y,F,IQ,LIQ,RQ,LRQ,1,PX,PY,PF,QX,QY,IFAIL)
The two calls will not produce identical results due to differences in the generation routines E01SEF and E01SGF. Details of the interpolant are passed from E01SGF through the arrays IQ and RQ rather than FNODES and RNW.
E01SHF also returns gradient values in QX and QY and allows evaluation at arrays of points rather than just single points.

E02 – Curve and Surface Fitting

E02ACF

Scheduled for withdrawal at Mark 27.
Replaced by E02ALF.
Old: CALL E02ACF(X, Y, N, A, M1, REF)
New: CALL E02ALF(N, X, Y, M1, A, REF, IFAIL)

E04 – Minimizing or Maximizing a Function

E04CCF/E04CCA

Withdrawn at Mark 24.
Replaced by E04CBF.
Old: CALL E04CCF(N,X,F,TOL,IW,W1,W2,W3,W4,W5,W6,FUNCT,MONIT,MAXCAL,   &
                 IFAIL)
        or
     CALL E04CCA(N,X,F,TOL,IW,W1,W2,W3,W4,W5,W6,FUNCT2,MONIT2,MAXCAL, &
                 IUSER,RUSER,IFAIL)
New: CALL E04CBF(N,X,F,TOLF,TOLX,FUNCT2,MONIT3,MAXCAL,IUSER,RUSER,    &
                 IFAIL)
       SUBROUTINE         MONIT3(FMIN,FMAX,SIM,N,NCALL,SERROR,VRATIO,IUSER,
                                 RUSER)
       INTEGER            N, NCALL, IUSER(*)
       REAL (KIND=nag_wp) FMIN, FMAX, SIM(N+1,N), SERROR, VRATIO, RUSER(*)

       CALL MONIT2(FMIN,FMAX,SIM,N,N+1,NCALL,IUSER,RUSER)
!      Add code here to monitor the values of SERROR and VRATIO, if necessary
       RETURN
       END

E04FDF

Withdrawn at Mark 19.
Replaced by E04FYF.
Old: CALL E04FDF(M,N,X,FSUMSQ,IW,LIW,W,LW,IFAIL)
New: CALL E04FYF(M,N,LSFUN,X,FSUMSQ,W,LW,IUSER,USER,IFAIL)
LSFUN appears in the argument list instead of the fixed-name subroutine LSFUN1 of E04FDF. LSFUN must be declared as EXTERNAL or be a module subprogram USEd in the calling (sub)program. In addition it has an extra two arguments, IUSER and USER, over and above those of LSFUN1. It may be derived from LSFUN1 as follows:
SUBROUTINE         LSFUN(M,N,XC,FVECC,IUSER,USER)
INTEGER            M, N, IUSER(*)
REAL (KIND=nag_wp) XC(N), FVECC(M), USER(*)

CALL LSFUN1(M,N,XC,FVECC)

RETURN
END
In general the extra arguments, IUSER and USER, should be declared in the calling program as IUSER 1 and USER 1 , but will not need initializing. If however, a COMMON block was used to pass information into LSFUN1, or get information from LSFUN1, then the arrays IUSER and USER should be declared appropriately and used for this purpose.

E04GCF

Withdrawn at Mark 19.
Replaced by E04GYF.
Old: CALL E04GCF(M,N,X,FSUMSQ,IW,LIW,W,LW,IFAIL)
New: CALL E04GYF(M,N,LSFUN,X,FSUMSQ,W,LW,IUSER,USER,IFAIL)
LSFUN appears in the argument list instead of the fixed-name subroutine LSFUN2 of E04GCF. LSFUN must be declared as EXTERNAL or be a module subprogram USEd in the calling (sub)program. In addition it has an extra two arguments, IUSER and USER, over and above those of LSFUN2. It may be derived from LSFUN2 as follows:
SUBROUTINE         LSFUN(M,N,XC,FVECC,FJACC,LJC,IUSER,USER)
INTEGER            M, N, LJC, IUSER(*)
REAL (KIND=nag_wp) XC(N), FVECC(M), FJACC(LJC,N), USER(*)

CALL LSFUN2(M,N,XC,FVECC,FJACC,LJC)

RETURN
END
In general the extra arguments, IUSER and USER, should be declared in the calling program as IUSER 1 and USER 1 , but will not need initializing. If however, a COMMON block was used to pass information through E04GCF into LSFUN2, or get information from LSFUN2, then the arrays IUSER and USER should be declared appropriately and used for this purpose.

E04GEF

Withdrawn at Mark 19.
Replaced by E04GZF.
Old: CALL E04GEF(M,N,X,FSUMSQ,IW,LIW,W,LW,IFAIL)
New: CALL E04GZF(M,N,LSFUN,X,FSUMSQ,W,LW,IUSER,USER,IFAIL)
LSFUN appears in the argument list instead of the fixed-name subroutine LSFUN2 of E04GEF. LSFUN must be declared as EXTERNAL or be a module subprogram USEd in the calling (sub)program. In addition it has an extra two arguments, IUSER and USER, over and above those of LSFUN2. It may be derived from LSFUN2 as follows:
SUBROUTINE         LSFUN(M,N,X,FVECC,FJACC,LJC,IUSER,USER)
INTEGER            M, N, LJC, IUSER(*)
REAL (KIND=nag_wp) XC(N), FVECC(M), FJACC(LJC,N), USER(*)

CALL LSFUN2(M,N,XC,FVECC,FJACC,LJC)

RETURN
END
In general the extra arguments, IUSER and USER, should be declared in the calling program as IUSER 1 and USER 1 , but will not need initializing. If however, a COMMON block was used to pass information through E04GEF into LSFUN2, or get information from LSFUN2, then the arrays IUSER and USER should be declared appropriately and used for this purpose.

E04HFF

Withdrawn at Mark 19.
Replaced by E04HYF.
Old: CALL E04HFF(M,N,X,FSUMSQ,IW,LIW,W,LW,IFAIL)
New: CALL E04HYF(M,N,LSFUN,LSHES,X,FSUMSQ,W,LW,IUSER,USER,IFAIL)
LSFUN and LSHES appear in the argument list instead of the fixed-name subroutines LSFUN2 and LSHES2 of E04HFF. LSFUN and LSHES must be declared as EXTERNAL or be a module subprogram USEd in the calling (sub)program. In addition they have an extra two arguments, IUSER and USER, over and above those of LSFUN2 and LSHES2. They may be derived from LSFUN2 and LSHES2 as follows:
SUBROUTINE         LSFUN(M,N,XC,FVECC,FJACC,LJC,IUSER,USER)
INTEGER            M, N, LJC, IUSER(*)
REAL (KIND=nag_wp) XC(N), FVECC(M), FJACC(LJC,N), USER(*)

CALL LSFUN2(M,N,XC,FVECC,FJACC,LJC)

RETURN
END

SUBROUTINE         LSHES(M,N,FVECC,XC,B,LB,IUSER,USER)
INTEGER            M, N, LB, IUSER(*)
REAL (KIND=nag_wp) FVECC(M), XC(N), B(LB), USER(*)

CALL LSHES2(M,N,FVECC,XC,B,LB)

RETURN
END
In general, the extra arguments, IUSER and USER, should be declared in the calling program as IUSER 1 and USER 1 , but will not need initializing. If, however, a COMMON block was used to pass information through E04HFF into LSFUN2 or LSHES2, or to get information from LSFUN2 or LSHES2, then the arrays IUSER and RUSER should be declared appropriately and used for this purpose.

E04JAF

Withdrawn at Mark 19.
Replaced by E04JYF.
Old: CALL E04JAF(N,IBOUND,BL,BU,X,F,IW,LIW,LW,IFAIL)
New: CALL E04JYF(N,IBOUND,FUNCT,BL,BU,X,F,IW,LIW,W,LW,IUSER,USER,IFAIL)
FUNCT appears in the argument list instead of the fixed-name subroutine FUNCT1 of E04JAF. FUNCT must be declared as EXTERNAL or be a module subprogram USEd in the calling (sub)program. In addition it has an extra two arguments, IUSER and USER, over and above those of FUNCT1. It may be derived from FUNCT1 as follows:
SUBROUTINE         FUNCT(N,XC,FC,IUSER,USER)
INTEGER            N, IUSER(*)
REAL (KIND=nag_wp) XC(N), FC, USER(*)

CALL FUNCT1(N,XC,FC)

RETURN
END
The extra arguments, IUSER and USER, should be declared in the calling program as IUSER 1 and USER 1 , but will not need initializing.

E04KAF

Withdrawn at Mark 19.
Replaced by E04KYF.
Old: CALL E04KAF(N,IBOUND,BL,BU,X,F,G,IW,LIW,W,LW,IFAIL)
New: CALL E04KYF(N,IBOUND,FUNCT,BL,BU,X,F,G,IW,LIW,W,LW,IUSER,USER,IFAIL)
FUNCT appears in the argument list instead of the fixed-name subroutine FUNCT2 of E04KAF. FUNCT must be declared as EXTERNAL or be a module subprogram USEd in the calling (sub)program. In addition it has an extra two arguments, IUSER and USER, over and above those of FUNCT2. It may be derived from FUNCT2 as follows:
SUBROUTINE         FUNCT(N,XC,FC,GC,IUSER,USER)
INTEGER            N, IUSER(*)
REAL (KIND=nag_wp) XC(N), FC, GC(N), USER(*)

CALL FUNCT2(N,XC,FC,GC)

RETURN
END
The extra arguments, IUSER and USER, should be declared in the calling program as IUSER 1 and USER 1 , but will not need initializing.

E04KCF

Withdrawn at Mark 19.
Replaced by E04KZF.
Old: CALL E04KCF(N,IBOUND,BL,BU,X,F,G,IW,LIW,W,LW,IFAIL)
New: CALL E04KZF(N,IBOUND,FUNCT,BL,BU,X,F,G,IW,LIW,W,LW,IUSER,USER,IFAIL)
FUNCT appears in the argument list instead of the fixed-name subroutine FUNCT2 of E04KCF. FUNCT must be declared as EXTERNAL or be a module subprogram USEd in the calling (sub)program. In addition it has an extra two arguments, IUSER and USER, over and above those of FUNCT2. It may be derived from FUNCT2 as follows:
SUBROUTINE         FUNCT(N,XC,FC,GC,IUSER,USER)
INTEGER            N, IUSER(*)
REAL (KIND=nag_wp) XC(N), FC, GC(N), USER(*)

CALL FUNCT2(N,XC,FC,GC)

RETURN
END
The extra arguments, IUSER and USER, should be declared in the calling program as IUSER 1 and USER 1 , but will not need initializing.

E04LAF

Withdrawn at Mark 19.
Replaced by E04LYF.
Old: CALL E04LAF(N,IBOUND,BL,BU,X,F,G,IW,LIW,W,LW,IFAIL)
New: CALL E04LYF(N,IBOUND,FUNCT,HESS,BL,BU,X,F,G,IW,LIW,W,LW,IUSER,USER, &
                 IFAIL)
FUNCT and HESS appear in the argument list instead of the fixed-name subroutines FUNCT2 and HESS2 of E04LAF. FUNCT and HESS must be declared as EXTERNAL or be a module subprogram USEd in the calling (sub)program. In addition they have an extra two arguments, IUSER and USER, over and above those of FUNCT2 and HESS2. They may be derived from FUNCT2 and HESS2 as follows:
SUBROUTINE         FUNCT(N,XC,FC,GC,IUSER,USER)
INTEGER            N, IUSER(*)
REAL (KIND=nag_wp) XC(N), FC, GC(N), USER(*)

CALL FUNCT2(N,XC,FC,GC)

RETURN
END
SUBROUTINE         HESS(N,XC,HESLC,LH,HESDC,IUSER,USER)
INTEGER            N, LH, IUSER(*)
REAL (KIND=nag_wp) XC(N), HESLC(LH), HESDC(N), USER(*)

CALL HESS2(N,XC,HESLC,LH,HESDC)

RETURN
END
In general, the extra arguments, IUSER and USER, should be declared in the calling program as IUSER 1 and USER 1 , but will not need initializing.

E04UNF

Withdrawn at Mark 22.
Replaced by E04USF/E04USA.
Old: CALL E04UNF(M,N,NCLIN,NCNLN,LDA,LDCJ,LDFJ,     &
                 LDR,A,BL,BU,Y,CONFUN,OBJFUN,ITER,  &
                 ISTATE,C,CJAC,F,FJAC,CLAMDA,OBJF,  &
                 R,X,IWORK,LIWORK,WORK,LWORK,IUSER, &
                 RUSER,IFAIL)
New: CALL E04USF(M,N,NCLIN,NCNLN,LDA,LDCJ,LDFJ,     &
                 LDR,A,BL,BU,Y,CONFUN,OBJFUN,ITER,  &
                 ISTATE,C,CJAC,F,FJAC,CLAMDA,OBJF,  &
                 R,X,IWORK,LIWORK,WORK,LWORK,IUSER, &
                 RUSER,IFAIL)
The specification of the subroutine OBJFUN must also be changed as follows:
Old: SUBROUTINE         OBJFUN(MODE,M,N,LDFJ,X,F,FJAC,NSTATE,IUSER,RUSER)
     INTEGER            MODE,M,N,LDFJ,NSTATE,IUSER(*)
     REAL (KIND=nag_wp) X(N),F(*),FJAC(LDFJ,*),RUSER(*)
New: SUBROUTINE         OBJFUN(MODE,M,N,LDFJ,NEEDFI,X,F,FJAC,NSTATE,      &
                        IUSER,RUSER)
     INTEGER            MODE,M,N,LDFJ,NEEDFI,NSTATE,IUSER(*)
     REAL (KIND=nag_wp) X(N),F(*),FJAC(LDFJ,*),RUSER(*)
See the routine documents for further information.

E04UPF

Withdrawn at Mark 19.
Replaced by E04USF/E04USA.
Old: CALL E04UPF(M,N,NCLIN,NCNLN,LDA,LDCJ,LDFJ,LDR,A,BL,BU, &
                 CONFUN,OBJFUN,ITER,ISTATE,C,CJAC,F,FJAC,   &
                 CLAMDA,OBJF,R,X,IWORK,LIWORK,WORK,LWORK,   &
                 IUSER,USER,IFAIL)
New: CALL E04USF(M,N,NCLIN,NCNLN,LDA,LDCJ,LDFJ,LDR,A,BL,BU, &
                 Y,CONFUN,OBJFUN,ITER,ISTATE,C,CJAC,F,FJAC, &
                 CLAMDA,OBJF, R,X,IWORK,LIWORK,WORK,LWORK,  &
                 IUSER,USER,IFAIL)
E04USF/E04USA contains one additional argument as follows:
  • Y M – real array.
Note that a call to E04UPF is the same as a call to E04USF/E04USA with Y i =0.0 , for i=1,2,…,M .
The specification of the subroutine OBJFUN must also be changed as follows:
Old: SUBROUTINE         OBJFUN(MODE,M,N,LDFJ,X,F,FJAC,NSTATE,IUSER,USER)
     INTEGER            MODE,M,N,LDFJ,NSTATE,IUSER(*)
     REAL (KIND=nag_wp) X(N),F(*),FJAC(LDFJ,*),USER(*)
New: SUBROUTINE         OBJFUN(MODE,M,N,LDFJ,NEEDFI,X,F,FJAC,NSTATE,     &
                        IUSER,USER)
     INTEGER            MODE,M,N,NEEFI,NSTATE,IUSER(*)
     REAL (KIND=nag_wp) X(N),F(*),FJAC(LDFJ,*),USER(*)
See the routine documents for further information.

E04ZCF/E04ZCA

Withdrawn at Mark 24.
There is no replacement for this routine.

F01 – Matrix Operations, Including Inversion

F01MAF

Withdrawn at Mark 19.
Replaced by F11JAF.
Existing programs should be modified to call F11JAF. The interfaces are significantly different and therefore precise details of a replacement call cannot be given. Please consult the appropriate routine document.

F02 – Eigenvalues and Eigenvectors

F02BBF

Withdrawn at Mark 19.
Replaced by F08FBF (DSYEVX).
Old:  CALL F02BBF(A,LDA,N,RLB,RUB,M,MM,R,V,LDV,D,E,E2,X,G,C,  &
                  ICOUNT,IFAIL)
New:  CALL DSYEVX('V','V','L',N,A,LDA,RLB,RUB,   &
                  0,0,2*X02AMF(),MM,R,V,LDV,WORK,LWORK,IWORK, &
                  JFAIL,INFO)
where R must have dimension at least max 1,N, WORK is a real array of length at least 4×N, LWORK is its actual length, JFAIL is an integer array of length at least max 1,N, and IWORK is an integer array of length at least 5×N. Note that in the call to F02BBF R needs only to be of dimension (M). Larger values of LWORK, up to some optimal value, may improve performance. Arguments C, ICOUNT, X, G, E2, E and D are not used.

F02BCF

Withdrawn at Mark 19.
Replaced by F02ECF.
Old: CALL F02BCF(A,IA,N,ALB,UB,M,MM,RR,RI,VR,IVR,VI,IVI,   &
                 INTGER,ICNT,C,B,IB,U,V,IFAIL)
New: CALL F02ECF('Moduli',N,A,IA,ALB,UB,M,MM,RR,RI,VR,IVR, &
                 VI,IVI,WORK,LWORK,ICNT,C,IFAIL)
where WORK is a real array of length at least (N×N+4) and LWORK is its actual length.

F02BDF

Withdrawn at Mark 19.
Replaced by F02GCF.
Old: CALL F02BDF(AR,IAR,AI,IAI,N,ALB,UB,M,MM,RR,RI,VR,IVR,  &
                 VI,IVI,INTGER,C,BR,IBR,BI,IBI,U,V,IFAIL)
New: DO 20 J = 1, N
        DO 10 I = 1, N
           A(I,J) = CMPLX(AR(I,J),AI(I,J),KIND=nag_wp)
  10    CONTINUE
  20 CONTINUE
     CALL F02GCF('Moduli',N,A,IA,ALB,UB,M,MM,R,V,IV,WORK,   &
                 LWORK,RWORK,INTGER,C,IFAIL)
     DO 30 I = 1, N
        RR(I) = REAL(R(I))
        RI(I) = AIMAG(R(I))
  30 CONTINUE
     DO 50 J = 1, MM
        DO 40 I = 1, N
           VR(I,J) = REAL(V(I,J))
           VI(I,J) = AIMAG(V(I,J))
  40    CONTINUE
  50 CONTINUE
where A is a complex array of dimension IA,N , R is a complex array of dimension (N), V is a complex array of dimension IV,M , WORK is a complex array of length at least N × N+2 , LWORK is its actual length, and RWORK is a real array of length at least 2×N .

F02BJF

Withdrawn at Mark 23.
Replaced by F08WAF (DGGEV).
Old: CALL F02BJF(N,A,LDA,B,LDB,EPS1,ALFR,ALFI,BETA,MATV,V,LDV,ITER,IFAIL)
New: IF (MATV) THEN
       JOBVR = 'V'
     ELSE
       JOBVR = 'N'
     ENDIF
     CALL DGGEV('N',JOBVR,N,A,LDA,B,LDB,ALFR,ALFI,BETA,VL,LDVL,           &
                 VR,LDVL,WORK,LWORK,INFO)
     IF (INFO.EQ.0) THEN
       ...

F02EAF

Withdrawn at Mark 23.
Replaced by F08PAF (DGEES).
Old: CALL F02EAF(JOB,N,A,LDA,WR,WI,Z,LDZ,WORK,LWORK,IFAIL)
New: LOGICAL SELECT
     EXTERNAL SELECT
     ...
     IF (JOB.EQ.'N') THEN
       JOBVS = 'N'
     ELSE
       JOBVS = 'V'
     END IF
     CALL DGEES(JOBVS,'N',SELECT,N,A,LDA,0,WR,WI,Z,LDZ,WORK, &
                 LWORK,BWORK,INFO)
     IF (INFO.EQ.0) THEN
        ....
     LOGICAL FUNCTION SELECT(AR,AI)
     REAL (KIND=nag_wp) :: AR, AI
     SELECT = .TRUE.
     RETURN
     ENDK

F02EBF

Withdrawn at Mark 23.
Replaced by F08NAF (DGEEV).
Old: CALL F02EBF(JOB,N,A,LDA,WR,WI,VR,LDVR,VI,LDVI,WORK,LWORK, &
                 IFAIL)
New: IF (JOB.EQ.'N') THEN
        JOBVR = 'N'
     ELSE
        JOBVR = 'V'
     END IF
     CALL DGEEV('N',JOBVR,N,A,LDA,WR,WI,VL,LDVL,VR1,LDVR1,     &
                 WORK,LWORK,INFO)
     IF (INFO.EQ.0) THEN
!       Eigenvector information is stored differently.
!       For complex conjugate pairs (that is, corresponding
!       to the j-th eigenvector such that WI(j) is nonzero,
!       and WI(j) = -WI(j+1)), the real and imaginary parts
!       of the first of the pair of eigenvectors are stored
!       as consecutive columns of VR1: VR1(:,j), VR1(:,j+1).
!       The second in the pair is just the conjugate of the
!       first, so can be constructed by negating the
!       elements in VR1(:,j+1).
!       If the j-th eigenvector is real (WI(j)=0), the
!       corresponding real eigenvector is stored in the
!       j-th column of VR1, VR1(1:N,j).

F02FAF

Withdrawn at Mark 23.
Replaced by F08FAF (DSYEV).
Old: CALL F02FAF(JOB,UPLO,N,A,LDA,W,WORK,LWORK,IFAIL)
New: CALL DSYEV(JOB,UPLO,N,A,LDA,W,WORK,LWORK,INFO)
     IF (INFO.EQ.0) THEN
       ...
The minimum workspace requirement has not increased but the requirement for optimal performance might be different. The workspace query mechanism (LWORK=-1) should be used to determine the requirement for optimal performance.

F02FCF

Withdrawn at Mark 23.
Replaced by F08FBF (DSYEVX).
Old: CALL F02FCF(JOB,RANGE,UPLO,N,A,LDA,WL,WU,IL,IU,MEST,M,   &
                 W,Z,LDZ,WORK,LWORK,IWORK,IFAIL)
New: CALL DSYEVX(JOB,RANGE,UPLO,N,A,LDA,WL,WU,IL,IU,ABSTOL,M, &
                 W,Z,LDZ,WORK,LWORK,IWORK,JFAIL,INFO)
     IF (INFO.EQ.0) THEN
       ...
The minimum workspace requirement has not increased but the requirement for optimal performance might be different. The workspace query mechanism (LWORK=-1) should be used to determine the requirement for optimal performance.

F02FDF

Withdrawn at Mark 23.
Replaced by F08SAF (DSYGV).
Old: CALL F02FDF(ITYPE,JOB,UPLO,N,A,LDA,B,LDB,W,WORK,LWORK,IFAIL)
New: CALL DSYGV(ITYPE,JOB,UPLO,N,A,LDA,B,LDB,W,WORK,LWORK,INFO)
     IF (INFO.EQ.0) THEN
       ...
The minimum workspace requirement has not increased but the requirement for optimal performance might be different. The workspace query mechanism (LWORK=-1) should be used to determine the requirement for optimal performance.

F02FHF

Withdrawn at Mark 23.
Replaced by F08UAF (DSBGV).
Old:  CALL F02FHF(N,MA,A,LDA,MB,B,LDB,D,WORK,LWORK,IFAIL)
New:  CALL DSBGV('N','U',N,MA,MB,A,LDA,B,LDB,D,Z,LDZ,WORK,INFO)
      IF (INFO.EQ.0) THEN
         ...
The order of eigenvalues in D changes from descending to ascending.
The minimum workspace requirement has changed to become LWORK=3×N

F02GAF

Withdrawn at Mark 23.
Replaced by F08PNF (ZGEES).
Old: CALL F02GAF(JOB,N,A,LDA,W,Z,LDZ,RWORK,WORK,LWORK,IFAIL)
New: LOGICAL BWORK(1)
     LOGICAL SELECT
     EXTERNAL SELECT
        ...
     IF (JOB.EQ.'N') THEN
        JOBVS = 'N'
     ELSE
        JOBVS = 'V'
     END IF
     CALL ZGEES(JOBVS,'N',SELECT,N,A,LDA,0,W,Z,LDZ,          &
                 WORK,LWORK,RWORK,BWORK,INFO)
     IF (INFO.NE.0) THEN
       ...
     LOGICAL FUNCTION SELECT(C)
     COMPLEX*16 C
     SELECT = .TRUE.
     RETURN
     END
The minimum workspace requirement has not increased but the requirement for optimal performance might be different. The workspace query mechanism (LWORK=-1) should be used to determine the requirement for optimal performance.

F02GBF

Withdrawn at Mark 23.
Replaced by F08NNF (ZGEEV).
Old: CALL F02GBF(JOB,N,A,LDA,W,V,LDV,RWORK,WORK,LWORK,IFAIL)
New: CALL ZGEEV('N',JOB,N,A,LDA,W,VL,LDVL,V,LDV,             &
                 WORK,LWORK,RWORK,INFO)
     IF (INFO.EQ.0) THEN
       ...

F02GJF

Withdrawn at Mark 23.
Replaced by F08WNF (ZGGEV).
Old:  CALL F02GJF(N,AR,LDAR,AI,LDAI,BR,LDBR,BI,LDBI,EPS1,ALFR,  &
                  ALFI,BETA,MATV,VR,LDVR,VI,LDVI,ITER,IFAIL)
New:  IF (MATV) THEN
         JOBVR = 'V'
      ELSE
         JOBVR = 'N'
      END IF

!     Set A=AR + iAI and B = BR+iBI

      CALL ZGGEV('N',JOBVR,N,A,LDA,B,LDB,ALPHA,BETA1,VL,LDVL,   &
                  V,LDV,WORK,LWORK,RWORK,INFO)
      IF (INFO.EQ.0) THEN
         ...
Note that the separated real and imaginary parts of input and output data in F02GJF has been replaced by combined complex types in F08WNF (ZGGEV).

F02HAF

Withdrawn at Mark 23.
Replaced by F08FNF (ZHEEV).
Old:  CALL F02HAF(JOB,UPLO,N,A,LDA,W,RWORK,WORK,LWORK,IFAIL)
New:  CALL ZHEEV(JOB,UPLO,N,A,LDA,W,WORK,LWORK,RWORK,INFO)
      IF (INFO.EQ.0) THEN
         ...
The minimum workspace requirement has not increased but the requirement for optimal performance might be different. The workspace query mechanism (LWORK=-1) should be used to determine the requirement for optimal performance.

F02HCF

Withdrawn at Mark 23.
Replaced by F08FPF (ZHEEVX).
Old:  CALL F02HCF(JOB,RANGE,UPLO,N,A,LDA,WL,WU,IL,IU,MEST,M,   &
                  W,Z,LDZ,WORK,LWORK,RWORK,IWORK,IFAIL)
New:  CALL ZHEEVX(JOB,RANGE,UPLO,N,A,LDA,WL,WU,IL,IU,ABSTOL,M, &
                  W,Z,LDZ,WORK,LWORK,RWORK,IWORK,JFAIL,INFO)
      IF (INFO.EQ.0) THEN
         ...
The minimum workspace requirement has not increased but the requirement for optimal performance might be different. The workspace query mechanism (LWORK=-1) should be used to determine the requirement for optimal performance.

F02HDF

Withdrawn at Mark 23.
Replaced by F08SNF (ZHEGV).
Old:  CALL F02HDF(ITYPE,JOB,UPLO,N,A,LDA,B,LDB,W,RWORK,WORK, &
                  LWORK,IFAIL)
New:  CALL ZHEGV(ITYPE,JOB,UPLO,N,A,LDA,B,LDB,W,WORK,LWORK,  &
                  RWORK,INFO)
      IF (INFO.EQ.0) THEN
         ...
The minimum workspace requirement has not increased but the requirement for optimal performance might be different. The workspace query mechanism (LWORK=-1) should be used to determine the requirement for optimal performance.

F02SDF

Scheduled for withdrawal at Mark 27.
Replaced by F12AGF and F12FGF.
The replacement routines F12FGF (symmetric case) and F12AGF (nonsymmetric case) are threaded for parallel execution in multithreaded implementations. These routines are based on the ARPACK package and make calls to BLAS/LAPACK routines. These may be threaded within the vendor library used by the implementation, which provides an additional opportunity for multithreaded performance.
Old: CALL F02SDF(N,MA+1,MB+1,A,LDA,B,LDB,SYM,RELEP,RMU,VEC,D,IWORK,WORK, &
                LWORK,IFAIL)
New: LICOMM = 140
     LCOMM = 3*N + 3*NCV*NCV + 6*NCV + 60
     ALLOCATE (COMM(LCOMM),DR(NCV),DI(NCV),RESID(N),V(N,NCV), &
               ICOMM(LICOMM))
     !   B is symmetric definite:
     IF (B_symm_def) THEN
       CALL F12AFF(N,1,NCV,ICOMM,LICOMM,COMM,LCOMM,IFAIL)
       CALL F12ADF('Generalized',ICOMM,COMM,IFAIL)
       CALL F12ADF('Shifted Inverse',ICOMM,COMM,IFAIL)
       CALL F12AGF(KL,KU,A,LDA,B,LDB,RMU,0.0,NCONV,DR,DI,V,N,RESID, &
                   V,LDV,COMM,ICOMM,IFAIL)
       VEC(1:N) = V(1:N,1)
     ELSE
       CALL F12AAF(N,NEV,NCV,ICOMM,LICOMM,COMM,LCOMM,IFAIL)
       ALLOCATE(C(LDA,N),IPIV(N),X(N),MX(N))
       C = A - RMU*B
       CALL DGBTRF(N,N,KL,KU,C,LDA,IPIV,INFO)
       IREVCM = 0
       DO WHILE (IREVCM/=5)
         CALL F12ABF(IREVCM,RESID,V,LDV,X,MX,NSHIFT,COMM,ICOMM,IFAIL)
       IF (IREVCM==-1 .OR. IREVCM==1) THEN
     !     Perform  x <--- OP*x = inv[A-SIGMA*B]*Bx.
           CALL DGBMV('N',N,N,KL,KU,ONE,B,LDB,X,1,ZERO,MX,1)
           X(1:N) = MX(1:N)
           CALL DGBTRS('N',N,KL,KU,1,C,LDA,IPIV,X,N,INFO)
         END IF
       END DO
     ! Post-process using F12ACF to compute eigenvalue.
       CALL F12ACF(NCONV,DR,DI,V,LDV,RMU,0.0,RESID,V,N,COMM,ICOMM,IFAIL)
       LR = DR(1)/(DR(1)**2+DI(1)**2) + RMU
     END IF

F02WDF

Scheduled for withdrawal at Mark 27.
Replaced by F02WUF and F08AEF (DGEQRF).
This routine is replaced for multithreaded performance and ability to benefit from vendor library performance (BLAS/LAPACK).
Note: only the multithreaded implementations of F02WDF were able to benefit from parallelism or vendor BLAS/LAPACK performance.
The Householder QU factorization part of the functionality can be achieved with F08AEF (DGEQRF). The action QT b can be computed by a call to F08AGF (DORMQR). The orthogonal matrix Q can be explicitly constructed, in-place, by a subsequent call to F08AFF (DORGQR).
If the singular value decomposition (SVD) of U is required, the result of F08AEF (DGEQRF) must be fed to F02WUF, remembering that the first orthogonal matrix of the SVD is called Q in F02WUF and R in F02WDF
Old: IFAIL = 0
     CALL F02WDF(M,N,A,LDA,WANTB,B,TOL,SVD,IRANK,Z,SV,WANTR,R, &
          LDR,WANTPT,PT,LDPT,WORK,LWORK,IFAIL)
New: LWORK = -1
     CALL DGEQRF(M,N,A,LDA,Z,WORK,LWORK,INFO)
     LWORK = ANINT(WORK(1))
     DEALLOCATE (WORK)
     ALLOCATE (WORK(LWORK))
     CALL DGEQRF(M,N,A,LDA,Z,WORK,LWORK,INFO)
     NCOLB = 1
     IF (WANTB) THEN
       CALL DORMQR('L','T',M,NCOLB,N,A,LDA,Z,B,M,WORK,LWORK,INFO)
     END IF
     IF (.NOT. SVD) THEN
       ! construct Q explicitly, overwrites A
       CALL DORGQR(M,M,A,LDA,Z,WORK,LWORK,INFO)
     ELSE
       ! SVD factorization, PT overwrites A
       DEALLOCATE (WORK)
       ALLOCATE (WORK(5*N))
       CALL F02WUF(N,A,LDA,NCOLB,B,M,WANTR,R,LDR,SV,WANTPT,WORK,IFAIL)
       ! compute rank
       IRANK = F06KLF(N,SV,1,TOL)
     END IF

F02WEF

Withdrawn at Mark 23.
Replaced by F08KBF (DGESVD).
Old:  CALL F02WEF(M,N,A,LDA,NCOLB,B,LDB,WANTQ,Q,LDQ,SV,WANTP,       &
                  PT,LDPT,WORK,IFAIL)
New:  IF (WANTQ) THEN
         JOBU = 'A'
      ELSE
         JOBU = 'N'
      END IF
      IF (WANTP) THEN
         JOBVT = 'A'
      ELSE
         JOBVT = 'N'
      END IF
      LWORK = -1
      CALL DGESVD(JOBU,JOBVT,M,N,A,LDA,SV,Q,LDQ,PT,LDPT,WORK,LWORK,INFO)
      LWORK = ANINT(WORK(1))
      ALLOCATE (W(LWORK))

      CALL DGESVD(JOBU,JOBVT,M,N,A,LDA,SV,Q,LDQ,PT,LDPT,W,LWORK,INFO)

      DEALLOCATE (W)
WORK must be a one-dimensional real array of length at least lwork given by: max 1, 3× min M,N + max M,N , 5× min M,N
Larger values of LWORK, up to some optimal value, may improve performance.
Please note that the facility to return QT⁢B is not provided so arguments WANTB and B are not required. Instead, F08KBF (DGESVD) has an option to return the entire M*M orthogonal matrix Q, referred to as U in its documentation, through its 8th argument.

F02XEF

Withdrawn at Mark 23.
Replaced by F08KPF (ZGESVD).
Old:  CALL F02XEF(M,N,A,LDA,NCOLB,B,LDB,WANTQ,Q,LDQ,SV,WANTP,        &
                  PH,LDPH,RWORK,CWORK,IFAIL)
New:  IF (WANTQ) THEN
         JOBU = 'A'
      ELSE
         JOBU = 'N'
      END IF
      IF (WANTP) THEN
         JOBVT = 'A'
      ELSE
         JOBVT = 'N'
      END IF
      LWORK = -1
      CALL ZGESVD(JOBU,JOBVT,M,N,A,LDA,SV,Q,LDQ,PT,LDPT,WORK,        &
                  LWORK,RWORK,INFO)
      LWORK = ANINT(WORK(1))
      ALLOCATE (W(LWORK))

      CALL ZGESVD(JOBU,JOBVT,M,N,A,LDA,SV,Q,LDQ,PT,LDPT,W,           &
                  LWORK,RWORK,INFO)

      DEALLOCATE (W)
WORK must be a one-dimensional complex array of length at least lwork given by max 1, 2× min M,N + max M,N
WORK must be a one-dimensional real array of length max 1,5×min M,N.
Larger values of LWORK, up to some optimal value, may improve performance.
Please note that the facility to return QH⁢B is not provided so arguments WANTB and B are not required. Instead, F08KPF (ZGESVD) has an option to return the entire M*M unitary matrix Q, referred to as U in its documentation, through its 8th argument.

F03 – Determinants

F03AAF

Withdrawn at Mark 25.
Replaced by F07ADF (DGETRF) and F03BAF.
Old: IFAIL = 0
     CALL F03AAF(A,LDA,N,DET,WKSPCE,IFAIL)
New: INTEGER IPIV(N)
     ...

     CALL DGETRF(N,N,A,LDA,IPIV,INFO)
     IFAIL = 0
     CALL F03BAF(N,A,LDA,IPIV,D,ID,IFAIL)
     DET = D*2**ID
Note: the real array WKSPCE has been replaced by the integer array IPIV for holding the pivots of the factorization.

F03ABF

Withdrawn at Mark 25.
Replaced by F07FDF (DPOTRF) and F03BFF.
Old: IFAIL = 0
     CALL F03ABF(A,LDA,N,DET,WKSPCE,IFAIL)
New: CALL DPOTRF('U',N,A,LDA,INFO)
     IFAIL = 0
     CALL F03BFF(N,A,LDA,D,ID,IFAIL)
     DET = D*2**ID
Note: the real array WKSPCE is no longer required. Also the upper triangular part of A, stored in A, has been replaced here by its Cholesky factorization; the lower triangular part of A can be used and overwritten by replacing 'U' by 'L' in the call to DPOTRF above.

F03ACF

Withdrawn at Mark 25.
Replaced by F07HDF (DPBTRF) and F03BHF.
Old: IFAIL = 0
     CALL F03ACF(A,LDA,N,M,DET,RL,LDRL,M1,IFAIL)
New: CALL DPBTRF('L',N,M,AB,LDAB,INFO)
     IFAIL = 0
     CALL F03BHF('L',N,KD,AB,LDAB,D,ID,IFAIL)
     DET = D*2**ID
Note: the storage of A in arrays A and AB is different. In fact AB ij=A ji, for i=1,2,…,m and j=max 1,i-m,…,i which conforms to the LAPACK banded storage scheme. The factorization is returned in AB rather than in a separate array (RL). The upper part of matrix A can also be stored in AB on input to DPBTRF.

F03ADF

Withdrawn at Mark 25.
Replaced by F07ARF (ZGETRF) and F03BNF.
Old: IFAIL = 0
     CALL F03ADF(A,LDA,N,DETR,DETI,WKSPCE,IFAIL)
New: INTEGER IPIV(N)
     ...
     CALL ZGETRF(N,N,A,LDA,IPIV,INFO)
     IFAIL = 0
     CALL F03BNF(N,A,LDA,IPIV,D,ID,IFAIL)
     DETR = REAL(D)*2**ID(1)
     DETI = AIMAG(D)*2**ID(2)
Note: the real array WKSPCE has been replaced by the integer array IPIV for holding the pivots of the factorization. The real and imaginary parts of the determinant are independently scaled.

F03AEF

Withdrawn at Mark 25.
Replaced by F07FDF (DPOTRF) and F03BFF.
Old: IFAIL = 0
     CALL F03AEF(N,A,LDA,P,D1,ID,IFAIL)
New: CALL DPOTRF('U',N,A,LDA,INFO)
     IFAIL = 0
     CALL F03BFF(N,A,LDA,D1,ID,IFAIL)
Note: the upper triangular part of A, stored in A, has been replaced here by its Cholesky factorization; the lower triangular part of A can be used and overwritten by replacing UPLO='U' by UPLO='L' in the call to F07FDF (DPOTRF) above.

F03AFF

Withdrawn at Mark 25.
Replaced by F07ADF (DGETRF) and F03BAF.
Old: IFAIL = 0
     CALL F03AFF(N,EPS,A,LDA,D1,ID,P,IFAIL)
New: INTEGER IPIV(N)
     ...
     CALL DGETRF(N,N,A,LDA,IPIV,INFO)
     IFAIL = 0
     CALL F03BAF(N,A,LDA,IPIV,D1,ID,IFAIL)
Note: real array P has been replaced by the integer array IPIV for holding the pivots of the factorization.

F04 – Simultaneous Linear Equations

F04AAF

Withdrawn at Mark 23.
Replaced by F07AAF (DGESV).
Old: CALL F04AAF(A,LDA,B,LDB,N,M,C,LDC,WKSPCE,IFAIL)
New: CALL DGESV(N,M,A,LDA,IPIV,B,LDB,INFO)
     IF (INFO.EQ.0) THEN
!       Answer now in B
        ...

F04ABF

Scheduled for withdrawal at Mark 28.
Replaced by F07FBF (DPOSVX).
F04ABF and F04ASF have been replaced by F07FBF (DPOSVX) for performance. The replacement routine is threaded by NAG and may also be threaded in the vendor library (BLAS/LAPACK).
Old: CALL F04ABF(A,LDA,B,LDB,N,M,C,LDC,WKSPCE,BB,LDBB,IFAIL)
New: CALL f04abf_wrap(a,lda,b,ldb,n,m,c,ldc,wkspce,bb,ldbb,ifail)

    Subroutine f04abf_wrap(a,lda,b,ldb,n,m,c,ldc,wkspce,bb,ldbb,ifail)
!     .. Use Statements ..
      Use nag_library, Only: dposvx, dsymm, nag_wp
!     .. Scalar Arguments ..
      Integer, Intent (In)             :: lda, ldb, ldbb, ldc, m, n
      Integer, Intent (Inout)          :: ifail
!     .. Array Arguments ..
      Real (Kind=nag_wp), Intent (Inout) :: a(lda,*), b(ldb,*)
      Real (Kind=nag_wp), Intent (Out)   :: bb(ldbb,m), c(ldc,m), wkspce(1)
!     .. Local Scalars ..
      Real (Kind=nag_wp)               :: rcond, alpha, beta
      Integer                          :: info, ldaf
      Character (1)                    :: equed
!     .. Local Arrays ..
      Real (Kind=nag_wp)               :: s(1)
      Real (Kind=nag_wp), Allocatable  :: af(:,:), work(:), ferr(:), berr(:)
      Integer, Allocatable             :: iwork(:)

      ldaf = n
      Allocate (af(ldaf,n),ferr(m),berr(m),work(3*n),iwork(n))
!     The NAG name equivalent of dposvx is f07fbf
      Call dposvx('N','Upper',n,m,a,lda,af,ldaf,equed,s,b,ldb,  &
          c,ldc,rcond,ferr,berr,work,iwork,info)

      ifail = info
      bb(1:n,1:m) = b(1:n,1:m)
      alpha = -1.0_nag_wp
      beta = 1.0_nag_wp
!     The NAG name equivalent of dgemm is f06yaf
      Call dsymm('L','U',n,m,alpha,a,lda,c,ldc,beta,bb,ldbb)

    End Subroutine f04abf_wrap

F04ACF

Withdrawn at Mark 23.
Replaced by F07HAF (DPBSV).
Old:  CALL F04ACF(A,LDA,B,LDB,N,M,IR,C,LDC,RL,LDRL,M1,IFAIL)
New:  CALL DPBSV('U',N,M,IR,AB,LDAB,B,LDB,INFO)
      IF (INFO.EQ.0) THEN
!        A and AB are stored differently.
!        AB may be regarded as the transpose of A, with the 'U' option.
!        Thus LDAB might be M+1
!        Answer now in B
         ...

F04ADF

Withdrawn at Mark 23.
Replaced by F07ANF (ZGESV).
Old:  CALL F04ADF(A,LDA,B,LDB,N,M,C,LDC,WKSPCE,IFAIL)
New:  CALL ZGESV(N,M,A,LDA,IPIV,B,LDB,INFO)
      IF (INFO.EQ.0) THEN
!        Answer now in B
         ...

F04AEF

Scheduled for withdrawal at Mark 28.
Replaced by F07ABF (DGESVX).
F04AEF and F04ATF have been replaced by F07ABF (DGESVX) for performance. The replacement routine is threaded by NAG and may also be threaded in the vendor library (BLAS/LAPACK).
Old: CALL F04AEF(A,LDA,B,LDB,N,M,C,LDC,WKSPCE,AA,LDAA,BB,LDBB,IFAIL)
New: CALL f04aef_wrap(a,lda,b,ldb,n,m,c,ldc,wkspce,aa,ldaa,bb,ldbb,ifail)
    Subroutine f04aef_wrap(a,lda,b,ldb,n,m,c,ldc,wkspce,aa,ldaa,bb,ldbb,ifail)
!     .. Use Statements ..
      Use nag_library, Only: dgesvx, dgemm, nag_wp
!     .. Scalar Arguments ..
      Integer, Intent (In)             :: lda, ldaa, ldb, ldbb, ldc, m, n
      Integer, Intent (Inout)          :: ifail
!     .. Array Arguments ..
      Real (Kind=nag_wp), Intent (Inout) :: a(lda,*), b(ldb,*)
      Real (Kind=nag_wp), Intent (Out)   :: bb(ldbb,m), c(ldc,m), aa(ldaa,n), &
                                            wkspce(1)
!     .. Local Scalars ..
      Real (Kind=nag_wp)               :: rcond, alpha, beta
      Integer                          :: info
      Character (1)                    :: equed
!     .. Local Arrays ..
      Real (Kind=nag_wp)               :: cscl(1), rscl(1)
      Real (Kind=nag_wp), Allocatable  :: work(:), ferr(:), berr(:)
      Integer, Allocatable             :: ipiv(:), iwork(:)

      Allocate (berr(m),ferr(m),work(4*n),ipiv(n),iwork(n))
!     The NAG name equivalent of dgesvx is f07abf
      Call dgesvx('N','N',n,m,a,lda,aa,ldaa,ipiv,equed,rscl,cscl,b,ldb, &
          c,ldc,rcond,ferr,berr,work,iwork,info)

      ifail = info
      bb(1:n,1:m) = b(1:n,1:m)
      alpha = -1.0_nag_wp
      beta = 1.0_nag_wp
!     The NAG name equivalent of dgemm is f06yaf
      Call dgemm('N','N',n,m,n,alpha,a,lda,c,ldc,beta,bb,ldbb)

    End Subroutine f04aef_wrap

F04AFF

Withdrawn at Mark 25.
There is no replacement for this routine.
The factorization and solution of a positive definite linear system can be handled by calls to routines from Chapter F07, e.g., F07FBF (DPOSVX).
For example:
Old: IFAIL = 0
     CALL F03AEF(N,A,LDA,P,D1,ID,IFAIL)
     CALL F04AFF(N,NRHS,A,LDA,P,B,LDB,EPS,X,LDX,BB,LDBB,K,IFAIL)
New: CALL DPOSVX('equil','upper',N,NRHS,A,LDA,AF,LDAF,'Yes',P,B, &
                 LDB,X,LDX,RCOND,FERR,BERR,WORK,IWORK,INFO)
     IFAIL = 0
     CALL F03BFF(N,A,LDA,D1,ID,IFAIL)

F04AGF

Withdrawn at Mark 25.
There is no replacement for this routine.
The factorization and solution of a positive definite linear system can be handled by calls to routines from Chapter F07, e.g., F07FAF (DPOSV).
For example:
Old: IFAIL = 0
     CALL F03AEF(N,A,LDA,P,D1,ID,IFAIL)
     CALL F04AGF(N,NRHS,A,LDA,P,B,LDB,X,LDX)
New: CALL DPOSV('upper',N,NRHS,A,LDA,B,LDB,INFO)
     IFAIL = 0
     CALL F03BFF(N,A,LDA,D1,ID,IFAIL)

F04AHF

Withdrawn at Mark 25.
There is no replacement for this routine.
The factorization and solution of a real general linear system can be handled by calls to routines from the Chapter F07, e.g., F07ABF (DGESVX).
For example:
Old: IFAIL = 0
     CALL F03AFF(N,EPS,A,LDA,D1,ID,P,IFAIL)
     CALL F04AHF(N,NRHS,A,LDA,AA,LDAA,P,B,LDB,EPS,X,LDX,BB,    &
                 LDBB,K,IFAIL)
New: CALL DGESVX('Equil','No trans',N,NRHS,A,LDA,AA,LDAA,IPIV, &
                 'Yes',R,C,B,LDB,X,LDX,RCOND,FERR,BERR,WORK,   &
                 IWORK,INFO)
     IFAIL = 0
     CALL F03BAF(N,A,LDA,IPIV,D1,ID,IFAIL)

F04AJF

Withdrawn at Mark 25.
There is no replacement for this routine.
The factorization and solution of a real general linear system can be handled by calls to routines from Chapter F07, e.g., F07AAF (DGESV).
For example:
Old: IFAIL = 0
     CALL F03AFF(N,EPS,A,LDA,D1,ID,P,IFAIL)
     CALL F04AJF(N,NRHS,A,LDA,P,B,LDB)
New: CALL DGESV(N,NRHS,A,LDA,IPIV,B,LDB,INFO)
     IFAIL = 0
     CALL F03BAF(N,A,LDA,IPIV,D1,ID,IFAIL)

F04ARF

Withdrawn at Mark 23.
Replaced by F07AAF (DGESV).
Old:  CALL F04ARF(A,LDA,B,N,C,WKSPCE,IFAIL)
New:  CALL DGESV(N,1,A,LDA,IPIV,B,N,INFO)
      IF (INFO.EQ.0) THEN
!        Answer now in B
         ...

F04ASF

Scheduled for withdrawal at Mark 28.
Replaced by F07FBF (DPOSVX).
F04ABF and F04ASF have been replaced by F07FBF (DPOSVX) for performance. The replacement routine is threaded by NAG and may also be threaded in the vendor library (BLAS/LAPACK).
Old: CALL F04ASF(A,LDA,B,N,C,WK1,WK2,IFAIL)
New: CALL f04asf_wrap(a,lda,b,n,c,wk1,wk2,ifail)
      Subroutine f04asf_wrap(a,lda,b,n,c,wk1,wk2,ifail)
  !     .. Use Statements ..
        Use nag_library, Only: dposvx, nag_wp
  !     .. Scalar Arguments ..
        Integer, Intent (In)             :: lda, n
        Integer, Intent (Inout)          :: ifail
  !     .. Array Arguments ..
        Real (Kind=nag_wp), Intent (Inout) :: a(lda,n), b(n)
        Real (Kind=nag_wp), Intent (Out) :: c(n), wk1(1), wk2(1)
  !     .. Local Scalars ..
        Real (Kind=nag_wp)               :: rcond
        Integer                          :: info, ldaf, m
        Character (1)                    :: equed
  !     .. Local Arrays ..
        Real (Kind=nag_wp)               :: s(1), ferr(1), berr(1)
        Real (Kind=nag_wp), Allocatable  :: af(:,:), work(:)
        Integer, Allocatable             :: iwork(:)

        ldaf = n
        m = 1
        Allocate (af(ldaf,n),work(3*n),iwork(n))
  !     The NAG name equivalent of dposvx is f07fbf
        Call dposvx('N','Upper',n,m,a,lda,af,ldaf,equed,s,b,n,  &
            c,n,rcond,ferr,berr,work,iwork,info)
        wk1(1) = rcond
        wk2(1) = berr(1)

        ifail = info
      End Subroutine f04asf_wrap

F04ATF

Scheduled for withdrawal at Mark 28.
Replaced by F07ABF (DGESVX).
F04AEF and F04ATF have been replaced by F07ABF (DGESVX) for performance. The replacement routine is threaded by NAG and may also be threaded in the vendor library (BLAS/LAPACK).
Old: Call F04ATF(A,LDA,B,N,C,AA,LDAA,WKS1,WKS2,IFAIL)
New: CALL f04atf_wrap(a,lda,b,n,c,aa,ldaa,wks1,wks2,ifail)
      Subroutine f04atf_wrap(a,lda,b,n,c,aa,ldaa,wks1,wks2,ifail)
  !     .. Use Statements ..
        Use nag_library, Only: dgesvx, nag_wp
  !     .. Scalar Arguments ..
        Integer, Intent (In)             :: lda, ldaa, n
        Integer, Intent (Inout)          :: ifail
  !     .. Array Arguments ..
        Real (Kind=nag_wp), Intent (Inout) :: a(lda,*), b(n)
        Real (Kind=nag_wp), Intent (Out)   :: c(n), aa(ldaa,n), wks1(1),
  wks2(1)
  !     .. Local Scalars ..
        Real (Kind=nag_wp)               :: rcond
        Integer                          :: info, m
        Character (1)                    :: equed
  !     .. Local Arrays ..
        Real (Kind=nag_wp)               :: cscl(1), rscl(1), ferr(1),
  berr(1)
        Real (Kind=nag_wp), Allocatable  :: work(:)
        Integer, Allocatable             :: ipiv(:), iwork(:)

        m = 1
        Allocate (work(4*n),ipiv(n),iwork(n))
  !     The NAG name equivalent of dgesvx is f07abf
        Call dgesvx('N','N',n,m,a,lda,aa,ldaa,ipiv,equed,rscl,cscl,b,n, &
            c,n,rcond,ferr,berr,work,iwork,info)

        ifail = info
        wks1(1) = rcond
        wks2(1) = berr(1)

      End Subroutine f04atf_wrap

F04EAF

Withdrawn at Mark 23.
Replaced by F07CAF (DGTSV).
Old:  CALL F04EAF(N,D,DU,DL,B,IFAIL)
New:  CALL DGTSV(N,1,DL(2),D,DU(2),B,N,INFO)
      IF (INFO.EQ.0) THEN
!        Answer now in B
         ...

F04FAF

Withdrawn at Mark 23.
Replaced by F07JAF (DPTSV), or F07JDF (DPTTRF) and F07JEF (DPTTRS).
Old:  CALL F04FAF(JOB,N,D,E,B,IFAIL)
New:  CALL DPTSV(N,1,D,E(2),B,1,INFO)
         ...

F04JAF

Withdrawn at Mark 23.
Replaced by F08KAF (DGELSS).
Old:  CALL F04JAF(M,N,A,LDA,B,TOL,SIGMA,IRANK,WORK,LWORK,IFAIL)
New:  CALL DGELSS(M,N,1,A,LDA,B,1,S,RCOND,IRANK,WORK,LWORK,INFO)
      IF (INFO.EQ.0) THEN
!        Answer now in B
!        Singular values now in S, not WORK.
!        The standard error is not computed
         ...
The minimum workspace requirement has changed from 4×N to 3 × min N,M + max 2 × min N,M ,max M,N,1 .

F04JDF

Withdrawn at Mark 23.
Replaced by F08KAF (DGELSS).
Old:  CALL F04JDF(M,N,A,LDA,B,TOL,SIGMA,IRANK,WORK,LWORK,IFAIL)
New:  CALL DGELSS(M,N,1,A,LDA,B,1,S,RCOND,IRANK,WORK,LWORK,INFO)
!     Note workspace requirements are different.
      IF (INFO.EQ.0) THEN
!        Answer now in B
!        Singular values now in S, not WORK.
!        The standard error is not computed
         ...
The minimum workspace requirement has changed from N×M+4 to 3 × min N,M + max 2 × min N,M ,max M,N,1 .

F04JLF

Withdrawn at Mark 23.
Replaced by F08ZBF (DGGGLM).
Old:  CALL F04JLF(M,N,P,A,LDA,B,LDB,D,X,Y,WORK,LWORK,IFAIL)
New:  CALL DGGGLM(M,N,P,A,LDA,B,LDB,D,X,Y,WORK,LWORK,INFO)
      IF (INFO.EQ.0) THEN
         ...
The minimum workspace requirement has not increased but the requirement for optimal performance might be different. The workspace query mechanism (LWORK=-1) should be used to determine the requirement for optimal performance.

F04JMF

Withdrawn at Mark 23.
Replaced by F08ZAF (DGGLSE).
Old:  CALL F04JMF(M,N,P,A,LDA,B,LDB,C,D,X,WORK,LWORK,IFAIL)
New:  CALL DGGLSE(M,N,P,A,LDA,B,LDB,C,D,X,WORK,LWORK,INFO)
      IF (INFO.EQ.0) THEN
         ...
The minimum workspace requirement has not increased but the requirement for optimal performance might be different. The workspace query mechanism (LWORK=-1) should be used to determine the requirement for optimal performance.

F04KLF

Withdrawn at Mark 23.
Replaced by F08ZPF (ZGGGLM).
Old: CALL F04KLF(M,N,P,A,LDA,B,LDB,D,X,Y,WORK,LWORK,IFAIL)
New: CALL ZGGGLM(M,N,P,A,LDA,B,LDB,D,X,Y,WORK,LWORK,INFO)
     IF (INFO.EQ.0) THEN
        ...

F04KMF

Withdrawn at Mark 23.
Replaced by F08ZNF (ZGGLSE).
Old: CALL F04KMF(M,N,P,A,LDA,B,LDB,C,D,X,WORK,LWORK,IFAIL)
New: CALL ZGGLSE(M,N,P,A,LDA,B,LDB,C,D,X,WORK,LWORK,INFO)
     IF (INFO.EQ.0) THEN
        ...

F04MAF

Withdrawn at Mark 19.
Replaced by F11JCF.
Existing programs should be modified to call F11JCF. The interfaces are significantly different and therefore precise details of a replacement call cannot be given. Please consult the appropriate routine document.

F04MBF

Withdrawn at Mark 19.
Replaced by F11GDF, F11GEF and F11GFF (or F11JCF or F11JEF).
If a user-defined preconditioner is required existing programs should be modified to call F11GDF, F11GEF and F11GFF. Otherwise F11JCF or F11JEF may be used. The interfaces for these routines are significantly different from that for F04MBF and therefore precise details of a replacement call cannot be given. Please consult the appropriate routine document.

F04YCF

Withdrawn at Mark 26.
Replaced by F04YDF.
F04YDF employs a better algorithm (see Higham N J and Tisseur F (2000) A block algorithm for matrix 1-norm estimation, with an application to 1-norm pseudospectra SIAM J. Matrix. Anal. Appl. 21 1185–1201).
Old: CALL F04YCF(ICASE,N,X,ESTNRM,WORK,IWORK,IFAIL)
New: CALL F04YDF(IREVCM,M,N,X,LDX,Y,LDY,ESTNRM,T,SEED,WORK,IWORK,IFAIL)
F04YDF returns an estimate of the 1-norm of a rectangular M×N matrix, whereas F04YCF only works with square matrices. The real array X, which was previously used to return matrix–vector products to F04YCF, has been replaced with two real arrays X LDX,* and Y LDY,* which are used to return matrix-matrix products to F04YDF. Here, LDX≥N, LDY≥M and the second dimensions of X and Y are at least of size T, where you can choose argument T. The sizes of the workspace arrays WORK and IWORK have been increased to M×T and 2×N+5×T+20 respectively. The integer SEED provides a seed for the random number generator used by F04YDF. The integer ICASE has been replaced by IREVCM, which can take the values 0, 1 or 2. See the routine documentation for F04YDF further details about the reverse communication interface.

F04ZCF

Withdrawn at Mark 26.
Replaced by F04ZDF.
F04ZDF employs a better algorithm (see Higham N J and Tisseur F (2000) A block algorithm for matrix 1-norm estimation, with an application to 1-norm pseudospectra SIAM J. Matrix. Anal. Appl. 21 1185–1201).
Old: CALL F04ZCF(ICASE,N,X,ESTNRM,WORK,IFAIL)
New: CALL F04ZDF(IREVCM,M,N,X,LDX,Y,LDY,ESTNRM,T,SEED,WORK,RWORK,IWORK,IFAIL)
F04ZDF returns an estimate of the 1-norm of a rectangular M×N matrix, whereas F04ZCF only works with square matrices. The complex array X, which was previously used to return matrix–vector products to F04ZCF, has been replaced with two complex arrays X LDX,* and Y LDY,* which are used to return matrix-matrix products to F04ZDF. Here, LDX≥N, LDY≥M and the second dimensions of X and Y are at least of size T, where you can choose the argument T. The sizes of the workspace arrays WORK and IWORK have been increased to M×T and 2×N+5×T+20 respectively and there is an additional real workspace array RWORK of size 2×N. The integer SEED provides a seed for the random number generator used by F04ZDF. The integer ICASE has been replaced by IREVCM, which can take the values 0, 1 or 2. See the routine documentation for F04ZDF for further details about the reverse communication interface.

F11 – Large Scale Linear Systems

F11BAF

Withdrawn at Mark 21.
Replaced by F11BDF.
Old: CALL F11BAF(METHOD,PRECON,NORM,WEIGHT,ITERM,N,M,TOL,MAXITN, &
                 ANORM,SIGMAX,MONIT,LWREQ,IFAIL)
New: CALL F11BDF(METHOD,PRECON,NORM,WEIGHT,ITERM,N,M,TOL,MAXITN, &
                 ANORM,SIGMAX,MONIT,WORK,LWORK,LWREQ,IFAIL)
F11BDF contains two additional arguments as follows:
  • WORK(LWORK) – real array.
  • LWORK – integer.
See the routine document for further information.

F11BBF

Withdrawn at Mark 21.
Replaced by F11BEF.
Old: CALL F11BBF(IREVCM,U,V,WORK,LWORK,IFAIL)
New: CALL F11BEF(IREVCM,U,V,WGT,WORK,LWORK,IFAIL)
WGT must be a one-dimensional real array of length at least n (the order of the matrix) if weights are to be used in the termination criterion, and 1 otherwise. Note that the call to F11BEF requires the weights to be supplied in WGT 1:n rather than WORK 1:n . The minimum value of the argument LWORK may also need to be changed.

F11BCF

Withdrawn at Mark 21.
Replaced by F11BFF.
Old: CALL F11BCF(ITN,STPLHS,STPRHS,ANORM,SIGMAX,IFAIL)
New: CALL F11BFF(ITN,STPLHS,STPRHS,ANORM,SIGMAX,WORK,LWORK,IFAIL)
F11BFF contains two additional arguments as follows:
  • WORK LWORK – real array.
  • LWORK – integer.
See the routine document for further information.

F11GAF

Withdrawn at Mark 22.
Replaced by F11GDF.
Old: CALL F11GAF(METHOD,PRECON,SIGCMP,NORM,WEIGHT,ITERM,N,TOL,MAXITN,    &
                 ANORM,SIGMAX,SIGTOL,MAXITS,MONIT,LWREQ,IFAIL)
New: CALL F11GDF(METHOD,PRECON,SIGCMP,NORM,WEIGHT,ITERM,N,TOL,MAXITN,    &
                 ANORM,SIGMAX,SIGTOL,MAXITS,MONIT,LWREQ,WORK,LWORK,IFAIL)
F11GDF contains two additional arguments as follows:
  • WORK LWORK – real array.
  • LWORK – integer.
See the routine document for further information.

F11GBF

Withdrawn at Mark 22.
Replaced by F11GEF.
Old: CALL F11GBF(IREVCM,U,V,WORK,LWORK,IFAIL)
New: CALL F11GEF(IREVCM,U,V,WGT,WORK,LWORK,IFAIL)
WGT must be a one-dimensional real array of length at least n (the order of the matrix) if weights are to be used in the termination criterion, and 1 otherwise. Note that the call to F11GEF requires the weights to be supplied in WGT 1:n rather than WORK 1:n . The minimum value of the argument LWORK may also need to be changed.

F11GCF

Withdrawn at Mark 22.
Replaced by F11GFF.
Old: CALL F11GCF(ITN,STPLHS,STPRHS,ANORM,SIGMAX,ITS,SIGERR,IFAIL)
New: CALL F11GFF(ITN,STPLHS,STPRHS,ANORM,SIGMAX,ITS,SIGERR,       &
                 WORK,LWORK,IFAIL)
F11GFF contains two additional arguments as follows:
  • WORK LWORK – real array.
  • LWORK – integer.
See the routine document for further information.

G01 – Simple Calculations on Statistical Data

G01AAF

Withdrawn at Mark 26.
Replaced by G01ATF.
Withdrawn because on output, additional information was needed to allow large datasets to be processed in blocks and the results combined through a call to G01AUF. This information is returned in RCOMM.
Old:
     CALL G01AAF(N,X,IWT,WT,XMEAN,S2,S3,S4,XMIN,XMAX,WTSUM,IFAIL)
New:
     PN = 0
     CALL G01ATF(N,X,IWT,WT,PN,XMEAN,S2,S3,S4,XMIN,XMAX,RCOMM,IFAIL)
     IWT = PN
     WTSUM = RCOMM(1)

G05 – Random Number Generators

G05CAF

Withdrawn at Mark 22.
Replaced by G05SAF.
Old: DO 20 I = 1, N
        X(I) = G05CAF(X(I))
  20 CONTINUE
New: CALL G05SAF(N,STATE,X,IFAIL)
The integer array STATE in the call to G05SAF contains information on the base generator being used. This array must have been initialized prior to calling G05SAF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05SAF is likely to be different from those produced by G05CAF.

G05CBF

Withdrawn at Mark 22.
Replaced by G05KFF.
Old: CALL G05CBF(I)
New: LSEED = 1
     SEED(1) = I
     GENID = 1
     SUBID = 1
     CALL G05KFF(GENID,SUBID,SEED,LSEED,STATE,LSTATE,IFAIL)
The integer array STATE in the call to G05KFF contains information on the base generator being used. The base generator is chosen via the integer arguments GENID and SUBID. The required length of the array STATE depends on the base generator chosen. Due to changes in the underlying code a sequence of values produced by using a random number generator initialized via a call to G05KFF is likely to be different from a sequence produced by a generator initialized by G05CBF, even if the same value for I is used.

G05CCF

Withdrawn at Mark 22.
Replaced by G05KGF.
Old: CALL G05CCF
New: GENID = 1
     SUBID = 1
     CALL G05KGF(GENID,SUBID,STATE,LSTATE,IFAIL)
The integer array STATE in the call to G05KGF contains information on the base generator being used. The base generator is chosen via the integer arguments GENID and SUBID. The required length of the array STATE depends on the base generator chosen.

G05CFF

Withdrawn at Mark 22.
Replaced by F06DFF.
Old: CALL G05CFF(IA,NI,XA,NX,IFAIL)
New: LSTATE = STATE(1)
     CALL F06DFF(LSTATE,STATE,1,CSTATE,1)
The state of the base generator for the group of routines G05KFF, G05KGF, G05KHF, G05KJF, G05NCF, G05NDF, G05PDF–G05PZF, G05RCF–G05RZF, G05S and G05T can be saved by simply creating a local copy of the array STATE. The first element of the STATE array contains the number of elements that are used by the random number generating routines, therefore either this number of elements can be copied, or the whole array (as defined in the calling program).

G05CGF

Withdrawn at Mark 22.
Replaced by F06DFF.
Old: CALL G05CGF(IA,NI,XA,NX,IFAIL)
New: LSTATE = CSTATE(1)
     CALL F06DFF(LSTATE,CSTATE,1,STATE,1)
The state of the base generator for the group of routines G05KFF, G05KGF, G05KHF, G05KJF, G05NCF, G05NDF, G05PDF–G05PZF, G05RCF–G05RZF, G05S and G05T can be restored by simply copying back the previously saved copy of the STATE array. The first element of the STATE array contains the number of elements that are used by the random number generating routines, therefore either this number of elements can be copied, or the whole array (as defined in the calling program).

G05DAF

Withdrawn at Mark 22.
Replaced by G05SQF.
Old: DO 10 I = 1, N
        X(I) = G05DAF(AA,BB)
  10 CONTINUE
New: A = MIN(AA,BB)
     B = MAX(AA,BB)
     IFAIL = 0
     CALL G05SQF(N,A,B,STATE,X,IFAIL)
The old routine G05DAF returns a single variate at a time, whereas the new routine G05SQF returns a vector of N values in one go. In G05SQF the minimum value must be held in the argument A and the maximum in argument B, therefore A<B. This was not the case for the equivalent arguments in G05DAF.
The integer array STATE in the call to G05SQF contains information on the base generator being used. This array must have been initialized prior to calling G05SQF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05SQF is likely to be different from those produced by G05DAF.

G05DBF

Withdrawn at Mark 22.
Replaced by G05SFF.
Old: DO 10 I = 1, N
        X(I) = G05DBF(AA)
  10 CONTINUE
New: A = ABS(AA)
     IFAIL = 0
     CALL G05SFF(N,A,STATE,X,IFAIL)
The old routine G05DBF returns a single variate at a time, whereas the new routine G05SFF returns a vector of N values in one go. In G05SFF argument A must be non-negative, this was not the case for the equivalent argument in G05DBF.
The integer array STATE in the call to G05SFF contains information on the base generator being used. This array must have been initialized prior to calling G05SFF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05SFF is likely to be different from those produced by G05DBF.

G05DCF

Withdrawn at Mark 22.
Replaced by G05SLF.
Old: DO 10 I = 1, N
        X(I) = G05DCF(A,BB)
  10 CONTINUE
New: B = ABS(BB)
     IFAIL = 0
     CALL G05SLF(N,A,B,STATE,X,IFAIL)
The old routine G05DCF returns a single variate at a time, whereas the new routine G05SLF returns a vector of N values in one go. In G05SLF the spread (argument A) must be positive, this was not the case for the equivalent arguments in G05DCF.
The integer array STATE in the call to G05SLF contains information on the base generator being used. This array must have been initialized prior to calling G05SLF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05SLF is likely to be different from those produced by G05DCF.

G05DDF

Withdrawn at Mark 22.
Replaced by G05SKF.
Old: DO 10 I = 1, N
        X(I) = G05DDF(XMU,SD)
  10 CONTINUE
New: VAR = SD**2
     IFAIL = 0
     CALL G05SKF(N,XMU,VAR,STATE,X,IFAIL)
The old routine G05DDF returns a single variate at a time, whereas the new routine G05SKF returns a vector of N values in one go. G05SKF expects the variance of the Normal distribution (argument VAR), compared to G05DDF which expected the standard deviation.
The integer array STATE in the call to G05SKF contains information on the base generator being used. This array must have been initialized prior to calling G05SKF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05SKF is likely to be different from those produced by G05DDF.

G05DEF

Withdrawn at Mark 22.
Replaced by G05SMF.
Old: DO 10 I = 1, N
        X(I) = G05DEF(XMU,SD)
  10 CONTINUE
New: VAR = SD**2
     IFAIL = 0
     CALL G05SMF(N,XMU,VAR,STATE,X,IFAIL)
The old routine G05DEF returns a single variate at a time, whereas the new routine G05SMF returns a vector of N values in one go. G05SMF expects the variance of the corresponding Normal distribution (argument VAR), compared to G05DEF which expected the standard deviation.
The integer array STATE in the call to G05SMF contains information on the base generator being used. This array must have been initialized prior to calling G05SMF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05SMF is likely to be different from those produced by G05DEF.

G05DFF

Withdrawn at Mark 22.
Replaced by G05SCF.
Old: DO 10 I = 1, N
        X(I) = G05DFF(XMED,B)
  10 CONTINUE
New: SEMIQR = ABS(B)
     IFAIL = 0
     CALL G05SCF(N,XMED,SEMIQR,STATE,X,IFAIL)
The old routine G05DFF returns a single variate at a time, whereas the new routine G05SCF returns a vector of N values in one go. G05SCF expects the semi-interquartile range (argument SEMIQR) to be non-negative, this was not the case for the equivalent argument in G05DFF.
The integer array STATE in the call to G05SCF contains information on the base generator being used. This array must have been initialized prior to calling G05SCF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05SCF is likely to be different from those produced by G05DFF.

G05DHF

Withdrawn at Mark 22.
Replaced by G05SDF.
Old: DO 10 I = 1, N
        X(I) = G05DHF(DF,IFAIL)
  10 CONTINUE
New: CALL G05SDF(N,DF,STATE,X,IFAIL)
The old routine G05DHF returns a single variate at a time, whereas the new routine G05SDF returns a vector of N values in one go.
The integer array STATE in the call to G05SDF contains information on the base generator being used. This array must have been initialized prior to calling G05SDF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05SDF is likely to be different from those produced by G05DHF.

G05DJF

Withdrawn at Mark 22.
Replaced by G05SNF.
Old: DO 10 I = 1, N
        X(I) = G05DJF(DF,IFAIL)
  10 CONTINUE
New: CALL G05SNF(N,DF,STATE,X,IFAIL)
The old routine G05DJF returns a single variate at a time, whereas the new routine G05SNF returns a vector of N values in one go.
The integer array STATE in the call to G05SNF contains information on the base generator being used. This array must have been initialized prior to calling G05SNF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05SNF is likely to be different from those produced by G05DJF.

G05DKF

Withdrawn at Mark 22.
Replaced by G05SHF.
Old: DO 10 I = 1, N
        X(I) = G05DKF(DF1,DF2,IFAIL)
  10 CONTINUE
New: CALL G05SHF(N,DF1,DF2,STATE,X,IFAIL)
The old routine G05DKF returns a single variate at a time, whereas the new routine G05SHF returns a vector of N values in one go.
The integer array STATE in the call to G05SHF contains information on the base generator being used. This array must have been initialized prior to calling G05SHF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05SHF is likely to be different from those produced by G05DKF.

G05DPF

Withdrawn at Mark 22.
Replaced by G05SSF.
Old: DO 10 I = 1, N
        X(I) = G05DPF(A,B,IFAIL)
  10 CONTINUE
New: CALL G05SSF(N,A,B,STATE,X,IFAIL)
The old routine G05DPF returns a single variate at a time, whereas the new routine G05SSF returns a vector of N values in one go.
The integer array STATE in the call to G05SSF contains information on the base generator being used. This array must have been initialized prior to calling G05SSF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05SSF is likely to be different from those produced by G05DPF.

G05DRF

Withdrawn at Mark 22.
Replaced by G05TKF.
Old: DO 10 I = 1, N
        X(I) = G05DRF(LAMDA,IFAIL)
  10 CONTINUE
New: MODE = 3
     CALL G05TJF(MODE,N,LAMBDA,R,LR,STATE,X,IFAIL)
The old routine G05DRF returns a single variate at a time, whereas the new routine G05TJF returns a vector of N values in one go. For efficiency, the new routine can make use of a reference vector, R. If, as in this case, the integer argument MODE is set to 3, the real reference vector R is not referenced, and its length, LR, need only be at least one.
The integer array STATE in the call to G05TJF contains information on the base generator being used. This array must have been initialized prior to calling G05TJF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05TJF is likely to be different from those produced by G05DRF.

G05DYF

Withdrawn at Mark 22.
Replaced by G05TLF.
Old: DO 10 I = 1, N
        X(I) = G05DYF(AA,BB)
  10 CONTINUE
New: IFAIL = 0
     A = MIN(AA,BB)
     B = MAX(AA,BB)
     CALL G05TLF(N,A,B,STATE,X,IFAIL)
The old routine G05DYF returns a single variate at a time, whereas the new routine G05TLF returns a vector of N values in one go. In G05TLF the minimum value must be held in the argument A and the maximum in argument B, therefore A≤B. This was not the case for the equivalent arguments in G05DYF.
The integer array STATE in the call to G05TLF contains information on the base generator being used. This array must have been initialized prior to calling G05TLF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05TLF is likely to be different from those produced by G05DYF.

G05DZF

Withdrawn at Mark 22.
Replaced by G05TBF.
Old: DO 20 I = 1, N
        X(I) = G05DZF(PP)
  20 CONTINUE
New: P = MAX(0.0D0,MIN(PP,1.0D0))
     IFAIL = 0
     CALL G05TBF(N,P,STATE,X,IFAIL)
The old routine G05DZF returns a single variate at a time, whereas the new routine G05TBF returns a vector of N values in one go. The real argument P in G05TBF must not be less than zero or greater than one, this was not the case for the equivalent argument in G05DZF.
The integer array STATE in the call to G05TBF contains information on the base generator being used. This array must have been initialized prior to calling G05TBF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05TBF is likely to be different from those produced by G05DZF.

G05EAF

Withdrawn at Mark 22.
Replaced by G05RZF.
Old: CALL G05EAF(XMU,M,C,LDC,EPS,R1,LR1,IFAIL)
New: MODE = 0
     CALL G05RZF(MODE,N,M,XMU,C,LDC,R,LR,STATE,X,LDX,IFAIL)
The old routine G05EAF sets up a reference vector for use by G05EZF. The functionality of both these routines has been combined into the single new routine G05RZF. Setting MODE=0 in the call to G05RZF only sets up the real reference vector R and hence mimics the functionality of G05EAF.
The length of the real reference vector, R, in G05RZF must be at least M×M+1+1. In contrast to the equivalent argument in G05EAF, this array must be allocated in the calling program.

G05EBF

Withdrawn at Mark 22.
Replaced by G05TLF.
There is no direct replacement for routine G05EBF. G05EBF sets up a reference vector for use by G05EYF, this reference vector is no longer required. The replacement routine for G05EYF is G05TLF.

G05ECF

Withdrawn at Mark 22.
Replaced by G05TJF.
Old: CALL G05ECF(LAMBDA,R1,LR1,IFAIL)
     DO 10 I = 1, N
        X(I) = G05EYF(R1,LR1)
  10 CONTINUE
New: MODE = 2
     CALL G05TJF(MODE,N,LAMBDA,R,LR,STATE,X,IFAIL)
The old routine G05ECF sets up a reference vector for use by G05EYF. The replacement routine G05TJF is now used to both set up a reference vector and generate the required variates. Setting MODE=0 in the call to G05TJF sets up the real reference vector R and hence mimics the functionality of G05ECF. Setting MODE=1 generates a series of variates from a reference vector mimicking the functionality of G05EYF for this particular distribution. Setting MODE=2 initializes the reference vector and generates the variates in one go.
The routine G05EYF returns a single variate at a time, whereas the new routine G05TJF returns a vector of N values in one go.
The length of the real reference vector, R, in G05TJF, must be allocated in the calling program in contrast to the equivalent argument in G05ECF, see the documentation for more details.
The integer array STATE in the call to G05TJF contains information on the base generator being used. This array must have been initialized prior to calling G05TJF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05TJF is likely to be different from those produced by a combination of G05ECF and G05EYF.

G05EDF

Withdrawn at Mark 22.
Replaced by G05TAF.
Old: CALL G05EDF(M,P,R1,LR1,IFAIL)
     DO 10 I = 1, N
        X(I) = G05EYF(R1,LR1)
  10 CONTINUE
New: MODE = 2
     CALL G05TAF(MODE,N,M,P,R,LR,STATE,X,IFAIL)
The old routine G05EDF sets up a reference vector for use by G05EYF. The replacement routine G05TAF is now used to both set up a reference vector and generate the required variates. Setting MODE=0 in the call to G05TAF sets up the real reference vector R and hence mimics the functionality of G05EDF. Setting MODE=1 generates a series of variates from a reference vector mimicking the functionality of G05EYF for this particular distribution. Setting MODE=2 initializes the reference vector and generates the variates in one go.
The routine G05EYF returns a single variate at a time, whereas the new routine G05TAF returns a vector of N values in one go.
The length of the real reference vector, R, in G05TAF, needs to be a different length from the equivalent argument in G05EDF, see the documentation for more details.
The integer array STATE in the call to G05TAF contains information on the base generator being used. This array must have been initialized prior to calling G05TAF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05TAF is likely to be different from those produced by a combination of G05EDF and G05EYF.

G05EEF

Withdrawn at Mark 22.
Replaced by G05THF.
Old: CALL G05EEF(M,P,R1,LR1,IFAIL)
     DO 10 I = 1, N
        X(I) = G05EYF(R1,LR1)
  10 CONTINUE
New: MODE = 2
     CALL G05THF(MODE,N,M,P,R,LR,STATE,X,IFAIL)
The old routine G05EEF sets up a reference vector for use by G05EYF. The replacement routine G05THF is now used to both set up a reference vector and generate the required variates. Setting MODE=0 in the call to G05THF sets up the real reference vector R and hence mimics the functionality of G05EEF. Setting MODE=1 generates a series of variates from a reference vector mimicking the functionality of G05EYF for this particular distribution. Setting MODE=2 initializes the reference vector and generates the variates in one go.
The routine G05EYF returns a single variate at a time, whereas the new routine G05THF returns a vector of N values in one go.
The length of the real reference vector, R, in G05THF, needs to be a different length from the equivalent argument in G05EEF, see the documentation for G05THF for more details.
The integer array STATE in the call to G05THF contains information on the base generator being used. This array must have been initialized prior to calling G05THF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05THF is likely to be different from those produced by a combination of G05EEF and G05EYF.

G05EFF

Withdrawn at Mark 22.
Replaced by G05TEF.
Old: CALL G05EFF(NS,M,NP,R1,LR1,IFAIL)
     DO 10 I = 1, N
        X(I) = G05EYF(R1,LR1)
  10 CONTINUE
New: MODE = 2
     CALL G05TEF(MODE,N,NS,NP,M,R,LR,STATE,X,IFAIL)
The old routine G05EFF sets up a reference vector for use by G05EYF. The replacement routine G05TEF is now used to both set up a reference vector and generate the required variates. Setting MODE=0 in the call to G05TEF sets up the real reference vector R and hence mimics the functionality of G05EFF. Setting MODE=1 generates a series of variates from a reference vector mimicking the functionality of G05EYF for this particular distribution. Setting MODE=2 initializes the reference vector and generates the variates in one go.
The routine G05EYF returns a single variate at a time, whereas the new routine G05TEF returns a vector of N values in one go.
The length of the real reference vector, R, in G05TEF, needs to be a different length from the equivalent argument in G05EFF, see the documentation for more details.
The integer array STATE in the call to G05TEF contains information on the base generator being used. This array must have been initialized prior to calling G05TEF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05TEF is likely to be different from those produced by a combination of G05EFF and G05EYF.

G05EGF

Withdrawn at Mark 22.
Replaced by G05PHF.
Old: CALL G05EGF(E,A,NA,B,NB,R,NR,VAR,IFAIL)
New: AVAR = B(1)**2
     IQ = NB - 1
     IF (AVAR.GT.0.0D0) THEN
        DO 10 I = 1, IQ
           THETA(I) = -B(I+1)/B(1)
  10    CONTINUE
     ELSE
        DO 20 I = 1, IQ
           THETA(I) = 0.0D0
  20    CONTINUE
     END IF
     MODE = 0
     CALL G05PHF(MODE,N,E,NA,A,IQ,THETA,AVAR,R,LR,STATE,VAR,X,IFAIL)
The real vector THETA must be of length at least IQ=NB-1.
The old routine G05EGF sets up a reference vector for use by G05EWF. The replacement routine G05PHF is now used to both set up a reference vector and generate the required variates. Setting MODE=0 in the call to G05PHF sets up the real reference vector R and hence mimics the functionality of G05EGF. When MODE=0, the integer array STATE in the call to G05PHF need not be set.

G05EHF

Withdrawn at Mark 22.
Replaced by G05NCF.
Old: CALL G05EHF(INDEX,N,IFAIL)
New: CALL G05NCF(INDEX,N,STATE,IFAIL)
The integer array STATE in the call to G05NCF contains information on the base generator being used. This array must have been initialized prior to calling G05NCF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05NCF is likely to be different from those produced by G05EHF.

G05EJF

Withdrawn at Mark 22.
Replaced by G05NDF.
Old: CALL G05EJF(IA,N,IZ,M,IFAIL)
New: CALL G05NDF(IA,N,IZ,M,STATE,IFAIL)
The integer array STATE in the call to G05NDF contains information on the base generator being used. This array must have been initialized prior to calling G05NDF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05NDF is likely to be different from those produced by G05EJF.

G05EWF

Withdrawn at Mark 22.
Replaced by G05PHF.
Old: CALL G05EGF(E,A,NA,B,NB,R,NR,VAR,IFAIL)
     DO 10 I = 1, N
        X(I) = G05EWF(R,NR,IFAIL)
  10 CONTINUE
New: AVAR = B(1)**2
     IQ = NB - 1
     IF (AVAR.GT.0.0D0) THEN
        DO 10 I = 1, IQ
           THETA(I) = -B(I+1)/B(1)
  10    CONTINUE
     ELSE
        DO 20 I = 1, IQ
           THETA(I) = 0.0D0
  20    CONTINUE
     END IF
     MODE = 2
     CALL G05PHF(MODE,N,E,NA,A,NB-1,THETA,AVAR,VAR,R,LR,STATE,X,IFAIL)
The real vector THETA must be of length at least IQ=NB-1.
The old routine G05EGF sets up a reference vector for use by G05EWF. The replacement routine G05PHF is now used to both set up a reference vector and generate the required variates. Setting the integer argument MODE to 0 in the call to G05PHF sets up the real reference vector R and hence mimics the functionality of G05EGF. Setting MODE to 1 generates a series of variates from a reference vector mimicking the functionality of G05EWF. Setting MODE to 2 initializes the reference vector and generates the variates in one go.
The integer array STATE in the call to G05PHF contains information on the base generator being used. This array must have been initialized prior to calling G05PHF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05PHF is likely to be different from those produced by G05EGF.

G05EXF

Withdrawn at Mark 22.
Replaced by G05TDF.
Old: CALL G05EXF(P,NP,IP1,ITYPE,R1,LR1,IFAIL)
     DO 10 I = 1, N
        X(I) = G05EYF(R1,LR1)
  10 CONTINUE
New: MODE = 2
     CALL G05TDF(MODE,N,P,NP,IP1,ITYPE,R,LR,STATE,X,IFAIL)
The old routine G05EXF sets up a reference vector for use by G05EYF. The replacement routine G05TDF is now used to both set up a reference vector and generate the required variates. Setting MODE=0 in the call to G05TDF sets up the real reference vector R and hence mimics the functionality of G05EXF. Setting MODE=1 generates a series of variates from a reference vector mimicking the functionality of G05EYF for this particular distribution. Setting MODE=2 initializes the reference vector and generates the variates in one go.
The routine G05EYF returns a single variate at a time, whereas the new routine G05TDF returns a vector of N values in one go.
The length of the real reference vector, R, in G05TDF must be allocated in the calling program in contrast to the equivalent argument in G05EXF, see the documentation for more details.
The integer array STATE in the call to G05TDF contains information on the base generator being used. This array must have been initialized prior to calling G05TDF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05TDF is likely to be different from those produced by a combination of G05EXF and G05EYF.

G05EYF

Withdrawn at Mark 22.
Replaced by G05TDF.
There is no direct replacement routine for G05EYF.
G05EYF is designed to generate random draws from a distribution defined by a reference vector. These reference vectors are created by other routines in Chapter G05, for example G05EBF, which have themselves been superseded. In order to replace a call to G05EYF you must identify which NAG routine generated the reference vector being used and look up its replacement. For example, to replace a call to G05EYF preceded by a call to G05EBF, as in:
    CALL G05EBF(M,IB,R,NR,IFAIL)
    X = G05EYF(R,NR)
you would need to look at the replacement routine for G05EBF.

G05EZF

Withdrawn at Mark 22.
Replaced by G05RZF.
Old: CALL G05EAF(XMU,N,C,LDC,EPS,R1,LR1,IFAIL)
     DO 20 I = 1, N
        CALL G05EZF(CX,M,R,NR,IFAIL)
        DO 30 J = 1, M
           X(I,J) = CX(J)
  30    CONTINUE
  20 CONTINUE
New: MODE = 2
     CALL G05RZF(MODE,N,M,XMU,C,LDC,R,LR,STATE,X,LDX,IFAIL)
The old routine G05EAF sets up a reference vector for use by G05EZF. The functionality of both these routines has been combined into the single new routine G05RZF. Setting MODE=2 in the call to G05RZF sets up the real reference vector R and generates the draws from the multivariate Normal distribution in one go.
The old routine G05EZF returns a single (M-dimensional vector) draw from the multivariate Normal distribution at a time, whereas the new routine G05RZF returns an N by M matrix of N draws in one go.
The integer array STATE in the call to G05RZF contains information on the base generator being used. This array must have been initialized prior to calling G05RZF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05RZF is likely to be different from those produced by G05EZF.

G05FAF

Withdrawn at Mark 22.
Replaced by G05SQF.
Old: CALL G05FAF(AA,BB,N,X)
New: A = MIN(AA,BB)
     B = MAX(AA,BB)
     IFAIL = 0
     CALL G05SQF(N,A,B,STATE,X,IFAIL)
In G05SQF the minimum value must be held in the argument A and the maximum in argument B, therefore A≤B. This was not the case for the equivalent arguments in G05FAF.
The integer array STATE in the call to G05SQF contains information on the base generator being used. This array must have been initialized prior to calling G05SQF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05SQF is likely to be different from those produced by G05FAF.

G05FBF

Withdrawn at Mark 22.
Replaced by G05SFF.
Old: CALL G05FBF(AA,N,X)
New: A = ABS(AA)
     IFAIL = 0
     CALL G05SFF(N,A,STATE,X,IFAIL)
In G05SFF argument A must be non-negative, this was not the case for the equivalent argument in G05FBF.
The integer array STATE in the call to G05SFF contains information on the base generator being used. This array must have been initialized prior to calling G05SFF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05SFF is likely to be different from those produced by G05FBF.

G05FDF

Withdrawn at Mark 22.
Replaced by G05SKF.
Old: CALL G05FDF(XMU,SD,N,X)
New: VAR = SD**2
     IFAIL = 0
     CALL G05SKF(N,XMU,VAR,STATE,X,IFAIL)
G05SKF expects the variance of the Normal distribution (argument VAR), compared to G05FDF which expected the standard deviation.
The integer array STATE in the call to G05SKF contains information on the base generator being used. This array must have been initialized prior to calling G05SKF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05SKF is likely to be different from those produced by G05FDF.

G05FEF

Withdrawn at Mark 22.
Replaced by G05SBF.
Old: CALL G05FEF(A,B,N,X,IFAIL)
New: CALL G05SBF(N,A,B,STATE,X,IFAIL)
The integer array STATE in the call to G05SBF contains information on the base generator being used. This array must have been initialized prior to calling G05SBF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05SBF is likely to be different from those produced by G05FEF.

G05FFF

Withdrawn at Mark 22.
Replaced by G05SJF.
Old: CALL G05FFF(A,B,N,X,IFAIL)
New: CALL G05SJF(N,A,B,STATE,X,IFAIL)
The integer array STATE in the call to G05SJF contains information on the base generator being used. This array must have been initialized prior to calling G05SJF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05SJF is likely to be different from those produced by G05FFF.

G05FSF

Withdrawn at Mark 22.
Replaced by G05SRF.
Old: CALL G05FSF(VK,N,X,IFAIL)
New: CALL G05SRF(N,VK,STATE,X,IFAIL)
The integer array STATE in the call to G05SRF contains information on the base generator being used. This array must have been initialized prior to calling G05SRF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05SRF is likely to be different from those produced by G05FSF.

G05GAF

Withdrawn at Mark 22.
Replaced by G05PXF.
Old: CALL G05GAF(SIDE,INIT,M,N,A,LDA,WK,IFAIL)
New: CALL G05PXF(SIDE,INIT,M,N,STATE,A,LDA,IFAIL)
The integer array STATE in the call to G05PXF contains information on the base generator being used. This array must have been initialized prior to calling G05PXF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05PXF is likely to be different from those produced by G05GAF.

G05GBF

Withdrawn at Mark 22.
Replaced by G05PYF.
Old: CALL G05GBF(N,D,C,LDC,EPS,WK,IFAIL)
New: CALL G05PYF(N,D,EPS,STATE,C,LDC,IFAIL)
The integer array STATE in the call to G05PYF contains information on the base generator being used. This array must have been initialized prior to calling G05PYF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05PYF is likely to be different from those produced by G05GBF.

G05HDF

Withdrawn at Mark 22.
Replaced by G05PJF.
Old: CALL G05HDF(MODE,K,IP,IQ,MEAN,PAR,LPAR,QQ,LDQQ,N,W,REF,LREF,  &
                 IWORK,LIWORK,IFAIL)
New: IF (MODE.EQ.'S') THEN
        IMODE = 0
     ELSE IF (MODE.EQ.'C') THEN
        IMODE = 1
     ELSE IF (MODE.EQ.'R') THEN
        IMODE = 3
     END IF
     LL = 0
     DO 30 L = 1, IP
        DO 20 I = 1, K
           DO 10 J = 1, K
              LL = LL + 1
              PHI(I,J,L) = PAR(LL)
  10       CONTINUE
  20    CONTINUE
  30 CONTINUE
     DO 60 L = 1, IQ-1
        DO 50 I = 1, K
           DO 40 J = 1, K
              LL = LL + 1
              THETA(I,J,L) = PAR(LL)
  40       CONTINUE
  50    CONTINUE
  60 CONTINUE
     IF (MEAN.EQ.'M') THEN
        DO 70 I = 1, K
           LL = LL + 1
           XMEAN(I) = PAR(LL)
  70    CONTINUE
     ELSE
        DO 80 I = 1, K
           XMEAN(I) = 0.0D0
  80    CONTINUE
     END IF
     LDW = N
     CALL G05PJF(IMODE,N,K,XMEAN,IP,PHI,IQ,THETA,QQ,LDQQ,REF,LREF, &
                 STATE,W,LDW,IWORK,LIWORK,IFAIL)
The integer argument IMODE should be set to 0, 1 or 3 in place of the argument MODE having settings of 'S', 'C' or 'R' respectively. The real array PHI should have length at least max 1,IP×K×K ; if dimensioned as PHI K,K,IP (as in the above example) then PHI i,j,l will contain the element PAR l-1 × k × k + i-1 × k + j . The real array THETA should have length at least max 1,IQ×K×K ; if dimensioned as THETA K,K,IQ (as in the above example) then THETA i,j,l will contain the element PAR IP × k × k + l-1 × k × k + i-1 × k + j . The real array XMEAN should have length at least K; if MEAN='M' then XMEAN i will contain the element PAR IP + IQ × k × k + i , otherwise XMEAN should contain an array of zero values.
The integer array STATE in the call to G05PJF contains information on the base generator being used. This array must have been initialized prior to calling G05PJF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05PJF is likely to be different from those produced by G05HDF.

G05HKF

Withdrawn at Mark 24.
Replaced by G05PDF.
Old: CALL G05HKF(DIST,NUM,IP,IQ,THETA,GAMMA,DF,HT,ET,FCALL,RVEC,IGEN,  &
                 ISEED,RWSAV,IFAIL)
New: CALL G05PDF(DIST,NUM,IP,IQ,THETA,GAMMA,DF,HT,ET,FCALL,R,LR,STATE, &
                 IFAIL)
The integer array STATE in the call to G05PDF contains information on the base generator being used. This array must have been initialized prior to calling G05PDF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05PDF is likely to be different from those produced by G05HKF.

G05HLF

Withdrawn at Mark 24.
Replaced by G05PEF.
Old: CALL G05HLF(DIST,NUM,IP,IQ,THETA,GAMMA,DF,HT,ET,FCALL,RVEC,IGEN,  &
                 ISEED,RWSAV,IFAIL)
New: CALL G05PEF(DIST,NUM,IP,IQ,THETA,GAMMA,DF,HT,ET,FCALL,R,LR,STATE, &
                 IFAIL)
The integer array STATE in the call to G05PEF contains information on the base generator being used. This array must have been initialized prior to calling G05PEF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05PEF is likely to be different from those produced by G05HLF.

G05HMF

Withdrawn at Mark 24.
Replaced by G05PFF.
Old: CALL G05HMF(DIST,NUM,IP,IQ,THETA,GAMMA,DF,HT,ET,FCALL,RVEC,IGEN,  &
                 ISEED,RWSAV,IFAIL)
New: CALL G05PFF(DIST,NUM,IP,IQ,THETA,GAMMA,DF,HT,ET,FCALL,R,LR,STATE, &
                 IFAIL)
The integer array STATE in the call to G05PFF contains information on the base generator being used. This array must have been initialized prior to calling G05PFF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization. Due to changes in the underlying code the sequence of values produced by G05PFF is likely to be different from those produced by G05HMF.

G05HNF

Withdrawn at Mark 24.
Replaced by G05PGF.
Old: CALL G05HNF(DIST,NUM,IP,IQ,THETA,DF,HT,ET,FCALL,RVEC,IGEN,ISEED, &
                 RWSAV,IFAIL)
New: CALL G05PGF(DIST,NUM,IP,IQ,THETA,DF,HT,ET,FCALL,RVEC,STATE,      &
                 IFAIL)
The integer array STATE in the call to G05PGF contains information on the base generator being used. This array must have been initialized prior to calling G05PGF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05KAF

Withdrawn at Mark 24.
Replaced by G05SAF.
Old: DO 20 I = 1, N
        X(I) = G05KAF(IGEN,ISEED)
  20 CONTINUE
New: CALL G05SAF(N,STATE,X,IFAIL)
The old routine G05KAF returns a single variate at a time, whereas the new routine G05SAF returns a vector of N values in one go.
The integer array STATE in the call to G05SAF contains information on the base generator being used. This array must have been initialized prior to calling G05SAF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05KBF

Withdrawn at Mark 24.
Replaced by G05KFF.
Old: G05KBF(IGEN,ISEED)
New: IF (IGEN.EQ.0) THEN
        CALL G05KFF(1,1,ISEED,LSEED,STATE,LSTATE,IFAIL)
     ELSE
        CALL G05KFF(2,IGEN,ISEED,LSEED,STATE,LSTATE,IFAIL)
     END IF

G05KCF

Withdrawn at Mark 24.
Replaced by G05KGF.
Old: CALL G05KCF(IGEN,ISEED)
New: IF (IGEN.EQ.0) THEN
        CALL G05KGF(1,1,STATE,LSTATE,IFAIL)
     ELSE
        CALL G05KGF(2,IGEN,STATE,LSTATE,IFAIL)
     END IF

G05KEF

Withdrawn at Mark 24.
Replaced by G05TBF.
Old: DO 20 I = 1, N
        X(I) = G05KEF(P,IGEN,ISEED,IFAIL)
  20 CONTINUE
New: CALL G05TBF(N,P,STATE,X,IFAIL)
The old routine G05KEF returns a single variate at a time, whereas the new routine G05TBF returns a vector of N values in one go.
The integer array STATE in the call to G05TBF contains information on the base generator being used. This array must have been initialized prior to calling G05TBF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05LAF

Withdrawn at Mark 24.
Replaced by G05SKF.
Old: CALL G05LAF(XMU,VAR,N,X,IGEN,ISEED,IFAIL)
New: CALL G05SKF(N,XMU,VAR,STATE,X,IFAIL)
The integer array STATE in the call to G05SKF contains information on the base generator being used. This array must have been initialized prior to calling G05SKF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05LBF

Withdrawn at Mark 24.
Replaced by G05SNF.
Old: CALL G05LBF(DF,N,X,IGEN,ISEED,IFAIL)
New: CALL G05SNF(N,DF,STATE,X,IFAIL)
The integer array STATE in the call to G05SNF contains information on the base generator being used. This array must have been initialized prior to calling G05SNF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05LCF

Withdrawn at Mark 24.
Replaced by G05SDF.
Old: CALL G05LCF(DF,N,X,IGEN,ISEED,IFAIL)
New: CALL G05SDF(N,DF,STATE,X,IFAIL)
The integer array STATE in the call to G05SDF contains information on the base generator being used. This array must have been initialized prior to calling G05SDF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05LDF

Withdrawn at Mark 24.
Replaced by G05SHF.
Old: CALL G05LDF(DF1,DF2,N,X,IGEN,ISEED,IFAIL)
New: CALL G05SHF(N,DF1,DF2,STATE,X,IFAIL)
The integer array STATE in the call to G05SHF contains information on the base generator being used. This array must have been initialized prior to calling G05SHF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05LEF

Withdrawn at Mark 24.
Replaced by G05SBF.
Old: CALL G05LEF(A,B,N,X,IGEN,ISEED,IFAIL)
New: CALL G05SBF(N,A,B,STATE,X,IFAIL)
The integer array STATE in the call to G05SBF contains information on the base generator being used. This array must have been initialized prior to calling G05SBF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05LFF

Withdrawn at Mark 24.
Replaced by G05SJF.
Old: CALL G05LFF(A,B,N,X,IGEN,ISEED,IFAIL)
New: CALL G05SJF(N,A,B,STATE,X,IFAIL)
The integer array STATE in the call to G05SJF contains information on the base generator being used. This array must have been initialized prior to calling G05SJF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05LGF

Withdrawn at Mark 24.
Replaced by G05SQF.
Old: CALL G05LGF(A,B,N,X,IGEN,ISEED,IFAIL)
New: CALL G05SQF(N,A,B,STATE,X,IFAIL)
The integer array STATE in the call to G05SQF contains information on the base generator being used. This array must have been initialized prior to calling G05SQF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05LHF

Withdrawn at Mark 24.
Replaced by G05SPF.
Old: CALL G05LHF(XMIN,XMAX,XMED,N,X,IGEN,ISEED,IFAIL)
New: CALL G05SPF(N,XMIN,XMED,XMAX,STATE,X,IFAIL)
The integer array STATE in the call to G05SPF contains information on the base generator being used. This array must have been initialized prior to calling G05SPF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05LJF

Withdrawn at Mark 24.
Replaced by G05SFF.
Old: CALL G05LJF(A,N,X,IGEN,ISEED,IFAIL)
New: CALL G05SFF(N,A,STATE,X,IFAIL)
The integer array STATE in the call to G05SFF contains information on the base generator being used. This array must have been initialized prior to calling G05SFF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05LKF

Withdrawn at Mark 24.
Replaced by G05SMF.
Old: CALL G05LKF(XMU,VAR,N,X,IGEN,ISEED,IFAIL)
New: CALL G05SMF(N,XMU,VAR,STATE,X,IFAIL)
The integer array STATE in the call to G05SMF contains information on the base generator being used. This array must have been initialized prior to calling G05SMF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05LLF

Withdrawn at Mark 24.
Replaced by G05SJF.
Old: CALL G05LLF(XMED,SEMIQR,N,X,IGEN,ISEED,IFAIL)
New: CALL G05SCF(N,XMED,SEMIQR,STATE,X,IFAIL)
The integer array STATE in the call to G05SCF contains information on the base generator being used. This array must have been initialized prior to calling G05SCF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05LMF

Withdrawn at Mark 24.
Replaced by G05SSF.
Old: CALL G05LMF(A,B,N,X,IGEN,ISEED,IFAIL)
New: CALL G05SSF(N,A,B,STATE,X,IFAIL)
The integer array STATE in the call to G05SSF contains information on the base generator being used. This array must have been initialized prior to calling G05SSF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05LNF

Withdrawn at Mark 24.
Replaced by G05SLF.
Old: CALL G05LNF(A,B,N,X,IGEN,ISEED,IFAIL)
New: CALL G05SLF(N,A,B,STATE,X,IFAIL)
The integer array STATE in the call to G05SLF contains information on the base generator being used. This array must have been initialized prior to calling G05SLF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05LPF

Withdrawn at Mark 24.
Replaced by G05SRF.
Old: CALL G05LPF(VK,N,X,IGEN,ISEED,IFAIL)
New: CALL G05SRF(N,VK,STATE,X,IFAIL)
The integer array STATE in the call to G05SRF contains information on the base generator being used. This array must have been initialized prior to calling G05SRF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05LQF

Withdrawn at Mark 24.
Replaced by G05SGF.
Old: CALL G05LQF(NMIX,A,WGT,N,X,IGEN,ISEED,IFAIL)
New: CALL G05SGF(N,NMIX,A,WGT,STATE,X,IFAIL)
The integer array STATE in the call to G05SGF contains information on the base generator being used. This array must have been initialized prior to calling G05SGF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05LXF

Withdrawn at Mark 24.
Replaced by G05RYF.
Old: CALL G05LXF(MODE,DF,M,XMU,C,LDC,N,X,LDX,IGEN,ISEED,R,LR,IFAIL)
New: IF (MODE == 0) THEN
       NMODE = 1
     ELSE IF (MODE == 1) THEN
       NMODE = 0
     ELSE
       NMODE = MODE
     END IF
     CALL G05RYF(NMODE,N,DF,M,XMU,C,LDC,R,LR,STATE,X,LDX,IFAIL)
The integer array STATE in the call to G05RYF contains information on the base generator being used. This array must have been initialized prior to calling G05RYF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05LYF

Withdrawn at Mark 24.
Replaced by G05RZF.
Old: G05LYF(MODE,M,XMU,C,LDC,N,X,LDX,IGEN,ISEED,R,LR,IFAIL)
New: IF (MODE == 0) THEN
       NMODE = 1
     ELSE IF (MODE == 1) THEN
       NMODE = 0
     ELSE
       NMODE = MODE
     END IF
     CALL G05RZF(NMODE,N,M,XMU,C,LDC,R,LR,STATE,X,LDX,IFAIL)
The integer array STATE in the call to G05RZF contains information on the base generator being used. This array must have been initialized prior to calling G05RZF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05LZF

Withdrawn at Mark 24.
Replaced by G05RZF.
Old: CALL G05LZF(MODE,M,XMU,C,LDC,X,IGEN,ISEED,R,LR,IFAIL)
New: IF (MODE == 0) THEN
       NMODE = 1
     ELSE IF (MODE == 1) THEN
       NMODE = 0
     ELSE
       NMODE = MODE
     END IF
     CALL G05RZF(NMODE,N,M,XMU,C,LDC,R,LR,STATE,X,LDX,IFAIL)
The integer array STATE in the call to G05RZF contains information on the base generator being used. This array must have been initialized prior to calling G05RZF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05MAF

Withdrawn at Mark 24.
Replaced by G05TLF.
Old: CALL G05MAF(A,B,N,X,IGEN,ISEED,IFAIL)
New: CALL G05TLF(N,A,B,STATE,X,IFAIL)
The integer array STATE in the call to G05TLF contains information on the base generator being used. This array must have been initialized prior to calling G05TLF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05MBF

Withdrawn at Mark 24.
Replaced by G05TCF.
Old: CALL G05MBF(MODE,P,N,X,IGEN,ISEED,R,NR,IFAIL)
New: CALL G05TCF(MODE,N,P,R,LR,STATE,X,IFAIL)
     DO 20 I = 1, N
        X(I) = X(I) + 1
  20 CONTINUE
G05MBF returned the number of trials required to get the first success, whereas G05TCF returns the number of failures before the first success, therefore the value returned by G05TCF is one less than the equivalent value returned from G05MBF.
The integer array STATE in the call to G05TCF contains information on the base generator being used. This array must have been initialized prior to calling G05TCF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05MCF

Withdrawn at Mark 24.
Replaced by G05THF.
Old: CALL G05MCF(MODE,M,P,N,X,IGEN,ISEED,R,NR,IFAIL)
New: CALL G05THF(MODE,N,M,P,R,LR,STATE,X,IFAIL)
The integer array STATE in the call to G05THF contains information on the base generator being used. This array must have been initialized prior to calling G05THF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05MDF

Withdrawn at Mark 24.
Replaced by G05TFF.
Old: CALL G05MDF(MODE,A,N,X,IGEN,ISEED,R,NR,IFAIL)
New: CALL G05TFF(MODE,N,A,R,LR,STATE,X,IFAIL)
The integer array STATE in the call to G05TFF contains information on the base generator being used. This array must have been initialized prior to calling G05TFF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05MEF

Withdrawn at Mark 24.
Replaced by G05TKF.
Old: CALL G05MEF(M,VLAMDA,X,IGEN,ISEED,IFAIL)
New: CALL G05TKF(M,VLAMDA,STATE,X,IFAIL)
The integer array STATE in the call to G05TKF contains information on the base generator being used. This array must have been initialized prior to calling G05TKF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05MJF

Withdrawn at Mark 24.
Replaced by G05TAF.
Old: CALL G05MJF(MODE,M,P,N,X,IGEN,ISEED,R,NR,IFAIL)
New: CALL G05TAF(MODE,N,M,P,R,LR,STATE,X,IFAIL)
The integer array STATE in the call to G05TAF contains information on the base generator being used. This array must have been initialized prior to calling G05TAF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05MKF

Withdrawn at Mark 24.
Replaced by G05TJF.
Old: CALL G05MKF(MODE,LAMBDA,N,X,IGEN,ISEED,R,NR,IFAIL)
New: CALL G05TJF(MODE,N,LAMBDA,R,LR,STATE,X,IFAIL)
The integer array STATE in the call to G05TJF contains information on the base generator being used. This array must have been initialized prior to calling G05TJF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05MLF

Withdrawn at Mark 24.
Replaced by G05TEF.
Old: CALL G05MLF(MODE,NS,NP,M,N,X,IGEN,ISEED,R,NR,IFAIL)
New: CALL G05TEF(MODE,N,NS,NP,M,R,LR,STATE,X,IFAIL)
The integer array STATE in the call to G05TEF contains information on the base generator being used. This array must have been initialized prior to calling G05TEF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05MRF

Withdrawn at Mark 24.
Replaced by G05TGF.
Old: CALL G05MRF(MODE,M,K,P,N,X,LDX,IGEN,ISEED,R,NR,IFAIL)
New: CALL G05TGF(MODE,N,M,K,P,R,LR,STATE,X,LDX,IFAIL)
The integer array STATE in the call to G05TGF contains information on the base generator being used. This array must have been initialized prior to calling G05TGF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05MZF

Withdrawn at Mark 24.
Replaced by G05TDF.
Old: CALL G05MZF(MODE,P,NP,IP1,ITYPE,N,X,IGEN,ISEED,R,NR,IFAIL)
New: CALL G05TDF(MODE,N,P,NP,IP1,ITYPE,R,LR,STATE,X,IFAIL)
The integer array STATE in the call to G05TDF contains information on the base generator being used. This array must have been initialized prior to calling G05TDF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05NAF

Withdrawn at Mark 24.
Replaced by G05NCF.
Old: CALL G05NAF(INDEX,N,IGEN,ISEED,IFAIL)
New: CALL G05NCF(INDEX,N,STATE,IFAIL)
The integer array STATE in the call to G05NCF contains information on the base generator being used. This array must have been initialized prior to calling G05NCF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05NBF

Withdrawn at Mark 24.
Replaced by G05NDF.
Old: CALL G05NBF(IPOP,N,ISAMPL,M,IGEN,ISEED,IFAIL)
New: CALL G05NDF(IPOP,N,ISAMPL,M,STATE,IFAIL)
The integer array STATE in the call to G05NDF contains information on the base generator being used. This array must have been initialized prior to calling G05NDF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05PAF

Withdrawn at Mark 24.
Replaced by G05PHF.
Old: CALL G05PAF(MODE,XMEAN,IP,PHI,IQ,THETA,AVAR,VAR,N,X,IGEN,ISEED,R, &
                 NR,IFAIL)
New: CALL G05PHF(MODE,N,XMEAN,IP,PHI,IQ,THETA,AVAR,R,LR,STATE,VAR,X,   &
                 IFAIL)
The integer array STATE in the call to G05PHF contains information on the base generator being used. This array must have been initialized prior to calling G05PHF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05PCF

Withdrawn at Mark 24.
Replaced by G05PJF.
Old: CALL G05PCF(MODE,K,XMEAN,IP,PHI,IQ,THETA,VAR,LDV,N,X,IGEN,ISEED,R,   &
                 NR,IWORK,LIWORK,IFAIL)
New: CALL G05PJF(MODE,N,K,XMEAN,IP,PHI,IQ,THETA,VAR,LDV,R,LR,STATE,X,LDX, &
                 IFAIL)
The integer array STATE in the call to G05PJF contains information on the base generator being used. This array must have been initialized prior to calling G05PJF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05QAF

Withdrawn at Mark 24.
Replaced by G05PXF.
Old: CALL G05QAF(SIDE,INIT,M,N,A,LDA,IGEN,ISEED,WK,IFAIL)
New: CALL G05PXF(SIDE,INIT,M,N,STATE,A,LDA,IFAIL)
The integer array STATE in the call to G05PXF contains information on the base generator being used. This array must have been initialized prior to calling G05PXF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05QBF

Withdrawn at Mark 24.
Replaced by G05PYF.
Old: CALL G05QBF(N,D,C,LDC,EPS,IGEN,ISEED,WK,IFAIL)
New: CALL G05PYF(N,D,EPS,STATE,C,LDC,IFAIL)
The integer array STATE in the call to G05PYF contains information on the base generator being used. This array must have been initialized prior to calling G05PYF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05QDF

Withdrawn at Mark 24.
Replaced by G05PZF.
Old: CALL G05QDF(MODE,NROW,NCOL,TOTR,TOTC,X,LDX,IGEN,ISEED,R,NR,IW,LIW, &
                 IFAIL)
New: CALL G05PZF(MODE,NROW,NCOL,TOTR,TOTC,R,LR,STATE,X,LDX,IFAIL)
The integer array STATE in the call to G05PZF contains information on the base generator being used. This array must have been initialized prior to calling G05PZF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05RAF

Withdrawn at Mark 24.
Replaced by G05RDF.
Old: CALL G05RAF(MODE,M,C,LDC,N,X,LDX,IGEN,ISEED,R,LR,IFAIL)
New: IF (MODE == 0) THEN
       NMODE = 1
     ELSE IF (MODE == 1) THEN
       NMODE = 0
     ELSE
       NMODE = MODE
     END IF
     CALL CALL G05RDF(NMODE,N,M,C,LDC,R,LR,STATE,X,LDX,IFAIL)
The integer array STATE in the call to G05RDF contains information on the base generator being used. This array must have been initialized prior to calling G05RDF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05RBF

Withdrawn at Mark 24.
Replaced by G05RCF.
Old: CALL G05RBF(MODE,DF,M,C,LDC,N,X,LDX,IGEN,ISEED,R,LR,IFAIL)
New: IF (MODE == 0) THEN
       NMODE = 1
     ELSE IF (MODE == 1) THEN
       NMODE = 0
     ELSE
       NMODE = MODE
     END IF
     CALL CALL G05RCF(NMODE,N,DF,M,C,LDC,R,LR,STATE,X,LDX,IFAIL)
The integer array STATE in the call to G05RCF contains information on the base generator being used. This array must have been initialized prior to calling G05RCF with a call to either G05KFF or G05KGF. The required length of the array STATE will depend on the base generator chosen during initialization.

G05YAF

Withdrawn at Mark 23.
Replaced by G05YLF and G05YMF.
Faure quasi-random numbers
Old: CALL G05YAF(.TRUE.,'F',ISKIP,IDIM,QUAS,IREF,IFAIL)
New: CALL G05YLF(4,IDIM,IREF,LIREF,ISKIP,IFAIL)
Old: CALL G05YAF(.FALSE.,'F',ISKIP,IDIM,QUAS,IREF,IFAIL)
New: CALL G05YMF(1,2,QUAS,LDQUAS,IREF,IFAIL)
Sobol quasi-random numbers
Old: CALL G05YAF(.TRUE.,'S',ISKIP,IDIM,QUAS,IREF,IFAIL)
New: CALL G05YLF(2,IDIM,IREF,LIREF,ISKIP,IFAIL)
Old: CALL G05YAF(.FALSE.,'S',ISKIP,IDIM,QUAS,IREF,IFAIL)
New: CALL G05YMF(1,2,QUAS,LDQUAS,IREF,IFAIL)
Neiderreiter quasi-random numbers
Old: CALL G05YAF(.TRUE.,'N',ISKIP,IDIM,QUAS,IREF,IFAIL)
New: CALL G05YLF(3,IDIM,IREF,LIREF,ISKIP,IFAIL)
Old: CALL G05YAF(.FALSE.,'N',ISKIP,IDIM,QUAS,IREF,IFAIL)
New: CALL G05YMF(1,2,QUAS,LDQUAS,IREF,IFAIL)

G05YBF

Withdrawn at Mark 23.
Replaced by G05YLF and either G05YJF or G05YKF.
This routine has been replaced by a suite of routines consisting of the relevant initialization routine followed by one of two possible generator routines.
Faure quasi-random numbers with Gaussian probability:
Old: CALL G05YBF(.TRUE.,'F',.FALSE.,MEAN,STD,ISKIP,IDIM,QUASI,IREF,IFAIL)
New: CALL G05YLF(4,IDIM,IREF,LIREF,ISKIP,IFAIL)
Old: CALL G05YBF(.FALSE.,'F',.FALSE.,MEAN,STD,ISKIP,IDIM,QUASI,IREF,IFAIL)
New: CALL G05YJF(MEAN,STD,N,QUASI,IREF,IFAIL)
Sobol quasi-random numbers with Gaussian probability:
Old: CALL G05YBF(.TRUE.,'S',.FALSE.,MEAN,STD,ISKIP,IDIM,QUASI,IREF,IFAIL)
New: CALL G05YLF(2,IDIM,IREF,LIREF,ISKIP,IFAIL)
Old: CALL G05YBF(.FALSE.,'S',.FALSE.,MEAN,STD,ISKIP,IDIM,QUASI,IREF,IFAIL)
New: CALL G05YJF(MEAN,STD,N,QUASI,IREF,IFAIL)
Neiderreiter quasi-random numbers with Gaussian probability:
Old: CALL G05YBF(.TRUE.,'N',.FALSE.,MEAN,STD,ISKIP,IDIM,QUASI,IREF,IFAIL)
New: CALL G05YLF(3,IDIM,IREF,LIREF,ISKIP,IFAIL)
Old: CALL G05YBF(.FALSE.,'N',.FALSE.,MEAN,STD,ISKIP,IDIM,QUASI,IREF,IFAIL)
New: CALL G05YJF(MEAN,STD,N,QUASI,IREF,IFAIL)
Faure quasi-random numbers with log Normal probability:
Old: CALL G05YBF(.TRUE.,'F',.TRUE.,MEAN,STD,ISKIP,IDIM,QUASI,IREF,IFAIL)
New: CALL G05YLF(4,IDIM,IREF,LIREF,ISKIP,IFAIL)
Old: CALL G05YBF(.FALSE.,'F',.TRUE.,MEAN,STD,ISKIP,IDIM,QUASI,IREF,IFAIL)
New: CALL G05YKF(MEAN,STD,N,QUASI,IREF,IFAIL)
Sobol quasi-random numbers with log Normal probability:
Old: CALL G05YBF(.TRUE.,'S',.TRUE.,MEAN,STD,ISKIP,IDIM,QUASI,IREF,IFAIL)
New: CALL G05YLF(2,IDIM,IREF,LIREF,ISKIP,IFAIL)
Old: CALL G05YBF(.FALSE.,'S',.TRUE.,MEAN,STD,ISKIP,IDIM,QUASI,IREF,IFAIL)
New: CALL G05YKF(MEAN,STD,N,QUASI,IREF,IFAIL)
Neiderreiter quasi-random numbers with log Normal probability:
Old: CALL G05YBF(.TRUE.,'N',.TRUE.,MEAN,STD,ISKIP,IDIM,QUASI,IREF,IFAIL)
New: CALL G05YLF(3,IDIM,IREF,LIREF,ISKIP,IFAIL)
Old: CALL G05YBF(.FALSE.,'N',.TRUE.,MEAN,STD,ISKIP,IDIM,QUASI,IREF,IFAIL)
New: CALL G05YKF(MEAN,STD,N,QUASI,IREF,IFAIL)

G05YCF

Withdrawn at Mark 24.
Replaced by G05YLF.
Old: CALL G05YCF(IDIM,IREF,IFAIL)
New: GENID = 4
     CALL G05YLF(GENID,IDIM,IREF,LIREF,ISKIP,IFAIL)

G05YDF

Withdrawn at Mark 24.
Replaced by G05YMF.
Old: CALL G05YDF(N,QUASI,IREF,IFAIL)
New: CALL G05YMF(N,QUAS,LDQUAS,IREF,IFAIL)

G05YEF

Withdrawn at Mark 24.
Replaced by G05YLF.
Old: CALL G05YEF(IDIM, IREF, ISKIP, IFAIL)
New: GENID = 2
     CALL G05YLF(GENID,IDIM,IREF,LIREF,ISKIP,IFAIL)

G05YFF

Withdrawn at Mark 24.
Replaced by G05YMF.
Old: CALL G05YFF(N,QUASI,IREF,IFAIL)
New: CALL G05YMF(N,QUAS,LDQUAS,IREF,IFAIL)

G05YGF

Withdrawn at Mark 24.
Replaced by G05YLF.
Old: CALL G05YGF(IDIM,IREF,ISKIP,IFAIL)
New: GENID = 3
     CALL G05YLF(GENID,IDIM,IREF,LIREF,ISKIP,IFAIL)

G05YHF

Withdrawn at Mark 24.
Replaced by G05YMF.
Old: CALL G05YHF(N,QUASI,IREF,IFAIL)
New: CALL G05YMF(N,RCORD,QUAS,LDQUAS,IREF,IFAIL)

G05ZAF

Withdrawn at Mark 22.
There is no replacement for this routine.
G05ZAF was used to select the underlying generator for the old style random number generation routines. These routines are no longer available and hence no direct replacement routine for G05ZAF is required. See G05KFF and G05KGF for details on how to select the underlying generator for the newer style routines.

G10 – Smoothing in Statistics

G10BAF

Scheduled for withdrawal at Mark 27.
Replaced by G10BBF.
Withdrawn primarily due to threadsafety. The replacement routine also introduces new functionality with respect to the automatic selection of a suitable window width.
Old: CALL G10BAF(N,X,WINDOW,SLO,SHI,NS,SMOOTH,T,USEFFT,FFT,IFAIL)

New: ALLOCATE(RCOMM,NS+20)
     CALL G10BBF(N,X,1,WINDOW,SLO,SHI,NS,SMOOTH,T,USEFFT,RCOMM,IFAIL)
     ! the next step is only required if the information in FFT
     ! was being used outside another call to G10BAF
     FFT(1:NS) = RCOMM(21:NS+20)

G13 – Time Series Analysis

G13DCF

Withdrawn at Mark 24.
Replaced by G13DDF.
Old: CALL G13DCF(K,N,IP,IQ,MEAN,PAR,NPAR,QQ,KMAX,W,PARHLD,EXACT,IPRINT,  &
                 CGETOL,MAXCAL,ISHOW,NITER,RLOGL,V,G,CM,LDCM,WORK,LWORK, &
                 IW,LIW,IFAIL)
New: CALL G13DDF(K,N,IP,IQ,MEAN,PAR,NPAR,QQ,KMAX,W,PARHLD,EXACT,IPRINT,  &
                 CGETOL,MAXCAL,ISHOW,NITER,RLOGL,V,G,CM,LDCM,IFAIL)
The workspace arguments WORK, LWORK, IW and LIW are no longer required in the call to G13DDF.

P01 – Error Trapping

P01ABF

Withdrawn at Mark 24.
There is no replacement for this routine.

X02 – Machine Constants

X02DAF

Withdrawn at Mark 24.
There is no replacement for this routine.

X02DJF

Withdrawn at Mark 24.
There is no replacement for this routine.
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


Multithreaded Routines : NAG Library, Mark 26

NAG Library

Multithreaded Routines

Many routines are threaded using OpenMP in multithreaded implementations of the NAG Library. These implementations are denoted by having a product code of the form 'FS_______', rather than 'FL_______' for serial NAG Library implementations. Please consult Section 8 of each routine document for further information.
Routine Name | Threaded by NAG | Calls BLAS or Lapack
a00aaf |  |
a00acf |  |
a00adf |  |
a02aaf |  |
a02abf |  |
a02acf |  |
c02aff |  |
c02agf |  |
c02ahf |  |
c02ajf |  |
c02akf | NAG | BLAS/LAPACK
c02alf | NAG | BLAS/LAPACK
c02amf | NAG | BLAS/LAPACK
c02anf | NAG | BLAS/LAPACK
c05auf |  |
c05avf |  |
c05awf |  |
c05axf |  |
c05ayf |  |
c05azf |  |
c05baf |  |
c05bbf |  |
c05qbf | NAG | BLAS/LAPACK
c05qcf | NAG | BLAS/LAPACK
c05qdf | NAG | BLAS/LAPACK
c05qsf | NAG | BLAS/LAPACK
c05rbf | NAG | BLAS/LAPACK
c05rcf | NAG | BLAS/LAPACK
c05rdf | NAG | BLAS/LAPACK
c05zdf |  |
c06baf |  |
c06dcf |  |
c06faf | NAG | BLAS/LAPACK
c06fbf | NAG | BLAS/LAPACK
c06fcf | NAG | BLAS/LAPACK
c06fff | NAG | BLAS/LAPACK
c06fjf | NAG | BLAS/LAPACK
c06fkf | NAG | BLAS/LAPACK
c06fxf | NAG | BLAS/LAPACK
c06laf |  |
c06lbf |  |
c06lcf |  |
c06paf | NAG | BLAS/LAPACK
c06pcf | NAG | BLAS/LAPACK
c06pff | NAG | BLAS/LAPACK
c06pjf | NAG | BLAS/LAPACK
c06pkf | NAG | BLAS/LAPACK
c06ppf | NAG | BLAS/LAPACK
c06pqf | NAG | BLAS/LAPACK
c06prf | NAG | BLAS/LAPACK
c06psf | NAG | BLAS/LAPACK
c06puf | NAG | BLAS/LAPACK
c06pvf | NAG | BLAS/LAPACK
c06pwf | NAG | BLAS/LAPACK
c06pxf | NAG | BLAS/LAPACK
c06pyf | NAG | BLAS/LAPACK
c06pzf | NAG | BLAS/LAPACK
c06raf | NAG | BLAS/LAPACK
c06rbf | NAG | BLAS/LAPACK
c06rcf | NAG | BLAS/LAPACK
c06rdf | NAG | BLAS/LAPACK
c06ref | NAG |
c06rff | NAG |
c06rgf | NAG |
c06rhf | NAG |
c09acf |  |
c09eaf | NAG |
c09ebf | NAG |
c09ecf |  |
c09edf |  |
c09faf | NAG |
c09fbf | NAG |
c09fcf |  |
c09fdf |  |
d01ahf |  |
d01ajf |  |
d01akf |  |
d01alf |  |
d01amf |  |
d01anf |  |
d01apf |  |
d01aqf |  |
d01arf |  |
d01asf |  |
d01atf |  |
d01auf |  |
d01bcf |  | BLAS/LAPACK
d01bdf |  |
d01daf | NAG |
d01eaf | NAG |
d01esf | NAG | BLAS/LAPACK
d01fbf |  |
d01fcf | NAG | BLAS/LAPACK
d01fdf |  |
d01gaf | NAG |
d01gbf | NAG |
d01gcf | NAG |
d01gdf | NAG |
d01gyf |  |
d01gzf |  |
d01jaf |  |
d01paf | NAG | BLAS/LAPACK
d01raf | NAG | BLAS/LAPACK
d01rcf |  |
d01rgf |  |
d01tbf |  |
d01tdf | NAG | BLAS/LAPACK
d01tef |  |
d01uaf |  |
d01ubf |  |
d01zkf | NAG |
d01zlf |  |
d02agf | NAG | BLAS/LAPACK
d02bgf |  |
d02bhf |  |
d02bjf |  | BLAS/LAPACK
d02cjf |  |
d02ejf | NAG | BLAS/LAPACK
d02gaf |  |
d02gbf |  | BLAS/LAPACK
d02haf |  | BLAS/LAPACK
d02hbf |  | BLAS/LAPACK
d02jaf |  | BLAS/LAPACK
d02jbf |  | BLAS/LAPACK
d02kaf |  |
d02kdf |  |
d02kef |  |
d02laf |  |
d02lxf |  |
d02lyf |  |
d02lzf |  |
d02mvf |  |
d02mzf |  |
d02nbf | NAG | BLAS/LAPACK
d02ncf | NAG | BLAS/LAPACK
d02ndf | NAG | BLAS/LAPACK
d02nef | NAG | BLAS/LAPACK
d02ngf | NAG | BLAS/LAPACK
d02nhf | NAG | BLAS/LAPACK
d02njf | NAG | BLAS/LAPACK
d02nmf | NAG | BLAS/LAPACK
d02nnf | NAG | BLAS/LAPACK
d02nrf |  |
d02nsf |  |
d02ntf |  |
d02nuf |  |
d02nvf |  |
d02nwf |  |
d02nxf |  |
d02nyf |  |
d02nzf |  |
d02pef |  | BLAS/LAPACK
d02pff |  | BLAS/LAPACK
d02pgf |  | BLAS/LAPACK
d02phf |  | BLAS/LAPACK
d02pqf |  |
d02prf |  |
d02psf |  | BLAS/LAPACK
d02ptf |  |
d02puf |  |
d02qff |  |
d02qgf |  |
d02qwf |  |
d02qxf |  |
d02qyf |  |
d02qzf |  |
d02raf |  |
d02saf |  | BLAS/LAPACK
d02tgf |  | BLAS/LAPACK
d02tlf | NAG | BLAS/LAPACK
d02tvf |  |
d02txf |  |
d02tyf |  | BLAS/LAPACK
d02tzf |  |
d02uaf | NAG | BLAS/LAPACK
d02ubf | NAG | BLAS/LAPACK
d02udf | NAG | BLAS/LAPACK
d02uef | NAG | BLAS/LAPACK
d02xjf |  |
d02xkf |  |
d02zaf |  |
d03eaf | NAG | BLAS/LAPACK
d03ebf |  |
d03ecf |  |
d03edf |  |
d03eef |  |
d03faf | NAG | BLAS/LAPACK
d03maf |  |
d03ncf | NAG | BLAS/LAPACK
d03ndf |  |
d03nef |  |
d03pcf | NAG | BLAS/LAPACK
d03pdf | NAG | BLAS/LAPACK
d03pef | NAG | BLAS/LAPACK
d03pff | NAG | BLAS/LAPACK
d03phf | NAG | BLAS/LAPACK
d03pjf | NAG | BLAS/LAPACK
d03pkf | NAG | BLAS/LAPACK
d03plf | NAG | BLAS/LAPACK
d03ppf | NAG | BLAS/LAPACK
d03prf | NAG | BLAS/LAPACK
d03psf | NAG | BLAS/LAPACK
d03puf |  |
d03pvf |  |
d03pwf |  |
d03pxf |  |
d03pyf |  |
d03pzf |  |
d03raf | NAG | BLAS/LAPACK
d03rbf | NAG | BLAS/LAPACK
d03ryf |  |
d03rzf |  |
d03uaf |  |
d03ubf |  |
d04aaf |  |
d05aaf | NAG | BLAS/LAPACK
d05abf | NAG | BLAS/LAPACK
d05baf |  |
d05bdf | NAG | BLAS/LAPACK
d05bef | NAG | BLAS/LAPACK
d05bwf |  |
d05byf | NAG | BLAS/LAPACK
d06aaf |  |
d06abf |  | BLAS/LAPACK
d06acf |  | BLAS/LAPACK
d06baf |  |
d06caf |  | BLAS/LAPACK
d06cbf | NAG |
d06ccf | NAG |
d06daf |  | BLAS/LAPACK
d06dbf |  |
e01aaf |  |
e01abf |  |
e01aef |  |
e01baf |  |
e01bef |  |
e01bff |  |
e01bgf |  |
e01bhf |  |
e01daf |  | BLAS/LAPACK
e01eaf |  |
e01ebf |  |
e01raf |  |
e01rbf |  |
e01saf |  |
e01sbf |  |
e01sgf | NAG | BLAS/LAPACK
e01shf | NAG |
e01tgf | NAG | BLAS/LAPACK
e01thf | NAG |
e01tkf | NAG | BLAS/LAPACK
e01tlf | NAG |
e01tmf | NAG | BLAS/LAPACK
e01tnf | NAG | BLAS/LAPACK
e01zmf | NAG | BLAS/LAPACK
e01znf | NAG | BLAS/LAPACK
e02adf |  |
e02aef |  |
e02aff |  |
e02agf |  |
e02ahf |  |
e02ajf |  |
e02akf |  |
e02alf |  | BLAS/LAPACK
e02baf |  |
e02bbf |  |
e02bcf |  |
e02bdf |  |
e02bef |  | BLAS/LAPACK
e02bff | NAG |
e02caf | NAG |
e02cbf | NAG |
e02daf |  |
e02dcf |  | BLAS/LAPACK
e02ddf |  | BLAS/LAPACK
e02def |  |
e02dff | NAG |
e02gaf |  |
e02gbf | NAG |
e02gcf |  |
e02jdf | NAG | BLAS/LAPACK
e02jef |  |
e02jff |  |
e02raf | NAG | BLAS/LAPACK
e02rbf |  |
e02zaf |  |
e02zkf | NAG |
e02zlf |  |
e04abf |  |
e04bbf |  |
e04cbf |  |
e04dgf |  | BLAS/LAPACK
e04djf |  |
e04dkf |  |
e04fcf | NAG | BLAS/LAPACK
e04fyf | NAG | BLAS/LAPACK
e04gbf | NAG | BLAS/LAPACK
e04gdf | NAG | BLAS/LAPACK
e04gyf | NAG | BLAS/LAPACK
e04gzf | NAG | BLAS/LAPACK
e04hcf |  |
e04hdf |  | BLAS/LAPACK
e04hef | NAG | BLAS/LAPACK
e04hyf | NAG | BLAS/LAPACK
e04jcf |  | BLAS/LAPACK
e04jyf |  |
e04kdf |  |
e04kyf |  |
e04kzf |  |
e04lbf |  |
e04lyf |  | BLAS/LAPACK
e04mff |  | BLAS/LAPACK
e04mgf |  |
e04mhf |  |
e04mwf |  |
e04mxf |  | BLAS/LAPACK
e04mzf |  |
e04ncf | NAG | BLAS/LAPACK
e04ndf |  |
e04nef |  |
e04nff |  | BLAS/LAPACK
e04ngf |  |
e04nhf |  |
e04nkf |  | BLAS/LAPACK
e04nlf |  |
e04nmf |  |
e04npf |  |
e04nqf |  | BLAS/LAPACK
e04nrf |  |
e04nsf |  |
e04ntf |  |
e04nuf |  |
e04nxf |  |
e04nyf |  |
e04pcf |  | BLAS/LAPACK
e04raf |  |
e04rdf |  |
e04ref |  |
e04rff |  |
e04rgf |  |
e04rhf |  |
e04rjf |  |
e04rkf |  |
e04rlf |  |
e04rnf |  |
e04rpf |  |
e04ryf |  |
e04rzf |  |
e04stf |  |
e04svf | NAG | BLAS/LAPACK
e04ucf | NAG | BLAS/LAPACK
e04udf |  |
e04uef |  |
e04uff | NAG | BLAS/LAPACK
e04ugf | NAG | BLAS/LAPACK
e04uhf |  |
e04ujf |  |
e04uqf |  |
e04urf |  |
e04usf | NAG | BLAS/LAPACK
e04vgf |  |
e04vhf |  | BLAS/LAPACK
e04vjf |  | BLAS/LAPACK
e04vkf |  |
e04vlf |  |
e04vmf |  |
e04vnf |  |
e04vrf |  |
e04vsf |  |
e04wbf |  |
e04wcf |  |
e04wdf |  | BLAS/LAPACK
e04wef |  |
e04wff |  |
e04wgf |  |
e04whf |  |
e04wkf |  |
e04wlf |  |
e04xaf |  |
e04yaf |  |
e04ybf |  |
e04ycf | NAG | BLAS/LAPACK
e04zmf |  |
e04znf |  |
e04zpf |  |
e05jaf | NAG |
e05jbf | NAG | BLAS/LAPACK
e05jcf | NAG |
e05jdf | NAG |
e05jef | NAG |
e05jff | NAG |
e05jgf | NAG |
e05jhf |  |
e05jjf |  |
e05jkf |  |
e05jlf |  |
e05saf | NAG | BLAS/LAPACK
e05sbf | NAG | BLAS/LAPACK
e05ucf | NAG | BLAS/LAPACK
e05usf | NAG | BLAS/LAPACK
e05zkf | NAG |
e05zlf |  |
f01abf | NAG | BLAS/LAPACK
f01adf | NAG | BLAS/LAPACK
f01blf |  |
f01brf |  |
f01bsf |  |
f01buf |  |
f01bvf |  |
f01ckf |  | BLAS/LAPACK
f01crf |  |
f01ctf | NAG |
f01cwf | NAG |
f01ecf | NAG | BLAS/LAPACK
f01edf | NAG | BLAS/LAPACK
f01eff | NAG | BLAS/LAPACK
f01ejf | NAG | BLAS/LAPACK
f01ekf | NAG | BLAS/LAPACK
f01elf | NAG | BLAS/LAPACK
f01emf | NAG | BLAS/LAPACK
f01enf | NAG | BLAS/LAPACK
f01epf | NAG | BLAS/LAPACK
f01eqf | NAG | BLAS/LAPACK
f01fcf | NAG | BLAS/LAPACK
f01fdf | NAG | BLAS/LAPACK
f01fff | NAG | BLAS/LAPACK
f01fjf | NAG | BLAS/LAPACK
f01fkf | NAG | BLAS/LAPACK
f01flf | NAG | BLAS/LAPACK
f01fmf | NAG | BLAS/LAPACK
f01fnf | NAG | BLAS/LAPACK
f01fpf | NAG | BLAS/LAPACK
f01fqf | NAG | BLAS/LAPACK
f01gaf | NAG | BLAS/LAPACK
f01gbf | NAG |
f01haf | NAG | BLAS/LAPACK
f01hbf | NAG |
f01jaf | NAG | BLAS/LAPACK
f01jbf | NAG | BLAS/LAPACK
f01jcf | NAG | BLAS/LAPACK
f01jdf | NAG | BLAS/LAPACK
f01jef | NAG | BLAS/LAPACK
f01jff | NAG | BLAS/LAPACK
f01jgf | NAG | BLAS/LAPACK
f01jhf | NAG | BLAS/LAPACK
f01jjf | NAG | BLAS/LAPACK
f01jkf | NAG | BLAS/LAPACK
f01kaf | NAG | BLAS/LAPACK
f01kbf | NAG | BLAS/LAPACK
f01kcf | NAG | BLAS/LAPACK
f01kdf | NAG | BLAS/LAPACK
f01kef | NAG | BLAS/LAPACK
f01kff | NAG | BLAS/LAPACK
f01kgf | NAG | BLAS/LAPACK
f01khf | NAG | BLAS/LAPACK
f01kjf | NAG | BLAS/LAPACK
f01kkf | NAG | BLAS/LAPACK
f01lef |  | BLAS/LAPACK
f01lhf |  | BLAS/LAPACK
f01mcf |  |
f01qgf |  | BLAS/LAPACK
f01qjf |  | BLAS/LAPACK
f01qkf |  | BLAS/LAPACK
f01rgf |  | BLAS/LAPACK
f01rjf |  | BLAS/LAPACK
f01rkf |  | BLAS/LAPACK
f01vaf |  |
f01vbf |  |
f01vcf |  |
f01vdf |  |
f01vef |  |
f01vff |  |
f01vgf |  |
f01vhf |  |
f01vjf |  |
f01vkf |  |
f01vlf |  |
f01vmf |  |
f01zaf |  |
f01zbf |  |
f01zcf |  |
f01zdf |  |
f02ecf | NAG | BLAS/LAPACK
f02ekf | NAG | BLAS/LAPACK
f02fjf | NAG | BLAS/LAPACK
f02fkf | NAG | BLAS/LAPACK
f02gcf | NAG | BLAS/LAPACK
f02jcf | NAG | BLAS/LAPACK
f02jqf | NAG | BLAS/LAPACK
f02wgf | NAG | BLAS/LAPACK
f02wuf | NAG | BLAS/LAPACK
f02xuf | NAG | BLAS/LAPACK
f03baf |  |
f03bff |  |
f03bhf |  |
f03bnf |  |
f04amf |  | BLAS/LAPACK
f04axf |  |
f04baf | NAG | BLAS/LAPACK
f04bbf | NAG | BLAS/LAPACK
f04bcf |  | BLAS/LAPACK
f04bdf | NAG | BLAS/LAPACK
f04bef | NAG | BLAS/LAPACK
f04bff | NAG | BLAS/LAPACK
f04bgf |  | BLAS/LAPACK
f04bhf |  | BLAS/LAPACK
f04bjf |  | BLAS/LAPACK
f04caf | NAG | BLAS/LAPACK
f04cbf | NAG | BLAS/LAPACK
f04ccf |  | BLAS/LAPACK
f04cdf | NAG | BLAS/LAPACK
f04cef | NAG | BLAS/LAPACK
f04cff | NAG | BLAS/LAPACK
f04cgf |  | BLAS/LAPACK
f04chf |  | BLAS/LAPACK
f04cjf |  | BLAS/LAPACK
f04dhf |  | BLAS/LAPACK
f04djf |  | BLAS/LAPACK
f04fef |  | BLAS/LAPACK
f04fff |  | BLAS/LAPACK
f04jgf | NAG | BLAS/LAPACK
f04lef |  |
f04lhf |  | BLAS/LAPACK
f04mcf |  |
f04mef |  | BLAS/LAPACK
f04mff |  | BLAS/LAPACK
f04qaf |  | BLAS/LAPACK
f04yaf |  | BLAS/LAPACK
f04ydf | NAG |
f04zdf | NAG |
f05aaf | NAG |
f06aaf |  |
f06baf |  |
f06bcf |  |
f06bef |  |
f06bhf |  |
f06blf |  |
f06bmf |  |
f06bnf |  |
f06bpf |  |
f06caf |  |
f06cbf |  |
f06ccf |  |
f06cdf |  |
f06chf |  |
f06clf |  |
f06dbf |  |
f06dff |  |
f06eaf |  |
f06ecf |  |
f06edf |  |
f06eff |  |
f06egf |  |
f06ejf |  |
f06ekf |  |
f06epf |  |
f06erf |  |
f06etf |  |
f06euf |  |
f06evf |  |
f06ewf |  |
f06exf |  |
f06faf |  |
f06fbf |  |
f06fcf |  | BLAS/LAPACK
f06fdf |  |
f06fef |  | BLAS/LAPACK
f06fgf |  |
f06fjf |  |
f06fkf |  |
f06flf |  |
f06fpf |  |
f06fqf |  |
f06frf |  | BLAS/LAPACK
f06fsf |  | BLAS/LAPACK
f06ftf |  | BLAS/LAPACK
f06fuf |  | BLAS/LAPACK
f06gaf |  |
f06gbf |  |
f06gcf |  |
f06gdf |  |
f06gff |  |
f06ggf |  |
f06grf |  |
f06gsf |  |
f06gtf |  |
f06guf |  |
f06gvf |  |
f06gwf |  |
f06hbf |  |
f06hcf |  | BLAS/LAPACK
f06hdf |  |
f06hgf |  |
f06hmf |  |
f06hpf |  |
f06hqf |  |
f06hrf |  | BLAS/LAPACK
f06htf |  | BLAS/LAPACK
f06jdf |  |
f06jjf |  |
f06jkf |  |
f06jlf |  |
f06jmf |  |
f06kcf |  | BLAS/LAPACK
f06kdf |  |
f06kef |  | BLAS/LAPACK
f06kff |  |
f06kjf |  |
f06klf |  |
f06kpf |  |
f06paf |  |
f06pbf |  |
f06pcf |  |
f06pdf |  |
f06pef |  |
f06pff |  |
f06pgf |  |
f06phf |  |
f06pjf |  |
f06pkf |  |
f06plf |  |
f06pmf |  |
f06ppf |  |
f06pqf |  |
f06prf |  |
f06psf |  |
f06qff |  |
f06qhf |  |
f06qjf |  |
f06qkf |  |
f06qmf |  |
f06qpf |  | BLAS/LAPACK
f06qqf |  |
f06qrf |  |
f06qsf |  |
f06qtf |  |
f06qvf |  |
f06qwf |  |
f06qxf |  |
f06raf |  |
f06rbf |  |
f06rcf |  |
f06rdf |  |
f06ref |  |
f06rjf |  |
f06rkf |  |
f06rlf |  |
f06rmf |  |
f06rnf |  |
f06rpf |  |
f06saf |  |
f06sbf |  |
f06scf |  |
f06sdf |  |
f06sef |  |
f06sff |  |
f06sgf |  |
f06shf |  |
f06sjf |  |
f06skf |  |
f06slf |  |
f06smf |  |
f06snf |  |
f06spf |  |
f06sqf |  |
f06srf |  |
f06ssf |  |
f06taf |  |
f06tbf |  |
f06tcf |  |
f06tdf |  |
f06tff |  |
f06thf |  |
f06tmf |  |
f06tpf |  | BLAS/LAPACK
f06tqf |  |
f06trf |  | BLAS/LAPACK
f06tsf |  | BLAS/LAPACK
f06ttf |  |
f06tvf |  |
f06twf |  |
f06txf |  |
f06tyf |  |
f06uaf |  |
f06ubf |  |
f06ucf |  |
f06udf |  |
f06uef |  |
f06uff |  |
f06ugf |  |
f06uhf |  |
f06ujf |  |
f06ukf |  |
f06ulf |  |
f06umf |  |
f06unf |  |
f06upf |  |
f06vjf |  |
f06vkf |  |
f06vxf |  |
f06waf |  |
f06wbf |  | BLAS/LAPACK
f06wcf |  | BLAS/LAPACK
f06wnf |  |
f06wpf |  | BLAS/LAPACK
f06wqf |  | BLAS/LAPACK
f06yaf | NAG |
f06ycf | NAG |
f06yff | NAG |
f06yjf | NAG |
f06ypf | NAG |
f06yrf | NAG | BLAS/LAPACK
f06zaf | NAG |
f06zcf | NAG |
f06zff | NAG |
f06zjf | NAG |
f06zpf | NAG |
f06zrf | NAG | BLAS/LAPACK
f06ztf | NAG |
f06zuf | NAG |
f06zwf | NAG | BLAS/LAPACK
f07aaf | NAG | BLAS/LAPACK
f07abf | NAG | BLAS/LAPACK
f07acf | NAG | BLAS/LAPACK
f07adf | NAG | BLAS/LAPACK
f07aef | NAG | BLAS/LAPACK
f07aff |  |
f07agf |  | BLAS/LAPACK
f07ahf | NAG | BLAS/LAPACK
f07ajf |  | BLAS/LAPACK
f07anf | NAG | BLAS/LAPACK
f07apf | NAG | BLAS/LAPACK
f07aqf | NAG | BLAS/LAPACK
f07arf | NAG | BLAS/LAPACK
f07asf | NAG | BLAS/LAPACK
f07atf |  |
f07auf |  | BLAS/LAPACK
f07avf | NAG | BLAS/LAPACK
f07awf |  | BLAS/LAPACK
f07baf | NAG | BLAS/LAPACK
f07bbf | NAG | BLAS/LAPACK
f07bdf | NAG | BLAS/LAPACK
f07bef | NAG | BLAS/LAPACK
f07bff |  |
f07bgf |  | BLAS/LAPACK
f07bhf | NAG | BLAS/LAPACK
f07bnf | NAG | BLAS/LAPACK
f07bpf | NAG | BLAS/LAPACK
f07brf | NAG | BLAS/LAPACK
f07bsf | NAG | BLAS/LAPACK
f07btf |  |
f07buf |  | BLAS/LAPACK
f07bvf | NAG | BLAS/LAPACK
f07caf |  |
f07cbf | NAG | BLAS/LAPACK
f07cdf |  |
f07cef |  |
f07cgf |  | BLAS/LAPACK
f07chf | NAG | BLAS/LAPACK
f07cnf |  |
f07cpf | NAG | BLAS/LAPACK
f07crf |  |
f07csf |  |
f07cuf |  | BLAS/LAPACK
f07cvf | NAG | BLAS/LAPACK
f07faf | NAG | BLAS/LAPACK
f07fbf | NAG | BLAS/LAPACK
f07fcf | NAG | BLAS/LAPACK
f07fdf | NAG | BLAS/LAPACK
f07fef | NAG | BLAS/LAPACK
f07fff |  |
f07fgf |  | BLAS/LAPACK
f07fhf | NAG | BLAS/LAPACK
f07fjf |  | BLAS/LAPACK
f07fnf | NAG | BLAS/LAPACK
f07fpf | NAG | BLAS/LAPACK
f07fqf | NAG | BLAS/LAPACK
f07frf | NAG | BLAS/LAPACK
f07fsf | NAG | BLAS/LAPACK
f07ftf |  |
f07fuf |  | BLAS/LAPACK
f07fvf | NAG | BLAS/LAPACK
f07fwf |  | BLAS/LAPACK
f07gaf | NAG | BLAS/LAPACK
f07gbf | NAG | BLAS/LAPACK
f07gdf |  | BLAS/LAPACK
f07gef | NAG | BLAS/LAPACK
f07gff |  |
f07ggf |  | BLAS/LAPACK
f07ghf | NAG | BLAS/LAPACK
f07gjf |  | BLAS/LAPACK
f07gnf | NAG | BLAS/LAPACK
f07gpf | NAG | BLAS/LAPACK
f07grf |  | BLAS/LAPACK
f07gsf | NAG | BLAS/LAPACK
f07gtf |  |
f07guf |  | BLAS/LAPACK
f07gvf | NAG | BLAS/LAPACK
f07gwf |  | BLAS/LAPACK
f07haf | NAG | BLAS/LAPACK
f07hbf | NAG | BLAS/LAPACK
f07hdf |  | BLAS/LAPACK
f07hef | NAG | BLAS/LAPACK
f07hff |  |
f07hgf |  | BLAS/LAPACK
f07hhf | NAG | BLAS/LAPACK
f07hnf | NAG | BLAS/LAPACK
f07hpf | NAG | BLAS/LAPACK
f07hrf |  | BLAS/LAPACK
f07hsf | NAG | BLAS/LAPACK
f07htf |  |
f07huf |  | BLAS/LAPACK
f07hvf | NAG | BLAS/LAPACK
f07jaf |  | BLAS/LAPACK
f07jbf | NAG | BLAS/LAPACK
f07jdf |  |
f07jef |  | BLAS/LAPACK
f07jgf |  |
f07jhf | NAG | BLAS/LAPACK
f07jnf |  | BLAS/LAPACK
f07jpf | NAG | BLAS/LAPACK
f07jrf |  |
f07jsf |  | BLAS/LAPACK
f07juf |  |
f07jvf | NAG | BLAS/LAPACK
f07kdf |  | BLAS/LAPACK
f07krf |  | BLAS/LAPACK
f07maf |  | BLAS/LAPACK
f07mbf | NAG | BLAS/LAPACK
f07mdf |  | BLAS/LAPACK
f07mef |  | BLAS/LAPACK
f07mgf |  | BLAS/LAPACK
f07mhf | NAG | BLAS/LAPACK
f07mjf |  | BLAS/LAPACK
f07mnf |  | BLAS/LAPACK
f07mpf | NAG | BLAS/LAPACK
f07mrf |  | BLAS/LAPACK
f07msf |  | BLAS/LAPACK
f07muf |  | BLAS/LAPACK
f07mvf | NAG | BLAS/LAPACK
f07mwf |  | BLAS/LAPACK
f07nnf |  | BLAS/LAPACK
f07npf | NAG | BLAS/LAPACK
f07nrf |  | BLAS/LAPACK
f07nsf |  | BLAS/LAPACK
f07nuf |  | BLAS/LAPACK
f07nvf | NAG | BLAS/LAPACK
f07nwf |  | BLAS/LAPACK
f07paf |  | BLAS/LAPACK
f07pbf | NAG | BLAS/LAPACK
f07pdf |  | BLAS/LAPACK
f07pef |  | BLAS/LAPACK
f07pgf |  | BLAS/LAPACK
f07phf | NAG | BLAS/LAPACK
f07pjf |  | BLAS/LAPACK
f07pnf |  | BLAS/LAPACK
f07ppf | NAG | BLAS/LAPACK
f07prf |  | BLAS/LAPACK
f07psf |  | BLAS/LAPACK
f07puf |  | BLAS/LAPACK
f07pvf | NAG | BLAS/LAPACK
f07pwf |  | BLAS/LAPACK
f07qnf |  | BLAS/LAPACK
f07qpf | NAG | BLAS/LAPACK
f07qrf |  | BLAS/LAPACK
f07qsf |  | BLAS/LAPACK
f07quf |  | BLAS/LAPACK
f07qvf | NAG | BLAS/LAPACK
f07qwf |  | BLAS/LAPACK
f07tef |  | BLAS/LAPACK
f07tgf |  | BLAS/LAPACK
f07thf | NAG | BLAS/LAPACK
f07tjf |  | BLAS/LAPACK
f07tsf |  | BLAS/LAPACK
f07tuf |  | BLAS/LAPACK
f07tvf | NAG | BLAS/LAPACK
f07twf |  | BLAS/LAPACK
f07uef | NAG | BLAS/LAPACK
f07ugf |  | BLAS/LAPACK
f07uhf | NAG | BLAS/LAPACK
f07ujf |  | BLAS/LAPACK
f07usf | NAG | BLAS/LAPACK
f07uuf |  | BLAS/LAPACK
f07uvf | NAG | BLAS/LAPACK
f07uwf |  | BLAS/LAPACK
f07vef | NAG | BLAS/LAPACK
f07vgf |  | BLAS/LAPACK
f07vhf | NAG | BLAS/LAPACK
f07vsf | NAG | BLAS/LAPACK
f07vuf |  | BLAS/LAPACK
f07vvf | NAG | BLAS/LAPACK
f07wdf | NAG | BLAS/LAPACK
f07wef |  | BLAS/LAPACK
f07wjf |  | BLAS/LAPACK
f07wkf |  | BLAS/LAPACK
f07wrf | NAG | BLAS/LAPACK
f07wsf |  | BLAS/LAPACK
f07wwf |  | BLAS/LAPACK
f07wxf |  | BLAS/LAPACK
f08aaf | NAG | BLAS/LAPACK
f08abf |  | BLAS/LAPACK
f08acf |  | BLAS/LAPACK
f08aef | NAG | BLAS/LAPACK
f08aff | NAG | BLAS/LAPACK
f08agf | NAG | BLAS/LAPACK
f08ahf |  | BLAS/LAPACK
f08ajf |  | BLAS/LAPACK
f08akf |  | BLAS/LAPACK
f08anf | NAG | BLAS/LAPACK
f08apf |  | BLAS/LAPACK
f08aqf |  | BLAS/LAPACK
f08asf | NAG | BLAS/LAPACK
f08atf | NAG | BLAS/LAPACK
f08auf | NAG | BLAS/LAPACK
f08avf |  | BLAS/LAPACK
f08awf |  | BLAS/LAPACK
f08axf |  | BLAS/LAPACK
f08baf | NAG | BLAS/LAPACK
f08bbf |  | BLAS/LAPACK
f08bcf |  | BLAS/LAPACK
f08bef |  | BLAS/LAPACK
f08bff | NAG | BLAS/LAPACK
f08bhf |  | BLAS/LAPACK
f08bkf |  | BLAS/LAPACK
f08bnf | NAG | BLAS/LAPACK
f08bpf |  | BLAS/LAPACK
f08bqf |  | BLAS/LAPACK
f08bsf |  | BLAS/LAPACK
f08btf | NAG | BLAS/LAPACK
f08bvf |  | BLAS/LAPACK
f08bxf |  | BLAS/LAPACK
f08cef |  | BLAS/LAPACK
f08cff |  | BLAS/LAPACK
f08cgf |  | BLAS/LAPACK
f08chf |  | BLAS/LAPACK
f08cjf |  | BLAS/LAPACK
f08ckf |  | BLAS/LAPACK
f08csf |  | BLAS/LAPACK
f08ctf |  | BLAS/LAPACK
f08cuf |  | BLAS/LAPACK
f08cvf |  | BLAS/LAPACK
f08cwf |  | BLAS/LAPACK
f08cxf |  | BLAS/LAPACK
f08faf | NAG | BLAS/LAPACK
f08fbf | NAG | BLAS/LAPACK
f08fcf | NAG | BLAS/LAPACK
f08fdf | NAG | BLAS/LAPACK
f08fef | NAG | BLAS/LAPACK
f08fff | NAG | BLAS/LAPACK
f08fgf | NAG | BLAS/LAPACK
f08flf |  |
f08fnf | NAG | BLAS/LAPACK
f08fpf | NAG | BLAS/LAPACK
f08fqf | NAG | BLAS/LAPACK
f08frf | NAG | BLAS/LAPACK
f08fsf | NAG | BLAS/LAPACK
f08ftf | NAG | BLAS/LAPACK
f08fuf | NAG | BLAS/LAPACK
f08gaf | NAG | BLAS/LAPACK
f08gbf | NAG | BLAS/LAPACK
f08gcf | NAG | BLAS/LAPACK
f08gef |  | BLAS/LAPACK
f08gff | NAG | BLAS/LAPACK
f08ggf |  | BLAS/LAPACK
f08gnf | NAG | BLAS/LAPACK
f08gpf | NAG | BLAS/LAPACK
f08gqf | NAG | BLAS/LAPACK
f08gsf |  | BLAS/LAPACK
f08gtf | NAG | BLAS/LAPACK
f08guf |  | BLAS/LAPACK
f08haf | NAG | BLAS/LAPACK
f08hbf | NAG | BLAS/LAPACK
f08hcf | NAG | BLAS/LAPACK
f08hef | NAG | BLAS/LAPACK
f08hnf | NAG | BLAS/LAPACK
f08hpf | NAG | BLAS/LAPACK
f08hqf | NAG | BLAS/LAPACK
f08hsf | NAG | BLAS/LAPACK
f08jaf | NAG | BLAS/LAPACK
f08jbf | NAG | BLAS/LAPACK
f08jcf | NAG | BLAS/LAPACK
f08jdf | NAG | BLAS/LAPACK
f08jef | NAG | BLAS/LAPACK
f08jff |  |
f08jgf | NAG | BLAS/LAPACK
f08jhf | NAG | BLAS/LAPACK
f08jjf | NAG |
f08jkf | NAG | BLAS/LAPACK
f08jlf | NAG | BLAS/LAPACK
f08jsf | NAG | BLAS/LAPACK
f08juf | NAG | BLAS/LAPACK
f08jvf | NAG | BLAS/LAPACK
f08jxf | NAG | BLAS/LAPACK
f08jyf | NAG | BLAS/LAPACK
f08kaf | NAG | BLAS/LAPACK
f08kbf | NAG | BLAS/LAPACK
f08kcf | NAG | BLAS/LAPACK
f08kdf | NAG | BLAS/LAPACK
f08kef | NAG | BLAS/LAPACK
f08kff | NAG | BLAS/LAPACK
f08kgf | NAG | BLAS/LAPACK
f08khf | NAG | BLAS/LAPACK
f08kjf |  | BLAS/LAPACK
f08knf | NAG | BLAS/LAPACK
f08kpf | NAG | BLAS/LAPACK
f08kqf | NAG | BLAS/LAPACK
f08krf | NAG | BLAS/LAPACK
f08ksf | NAG | BLAS/LAPACK
f08ktf | NAG | BLAS/LAPACK
f08kuf | NAG | BLAS/LAPACK
f08lef |  | BLAS/LAPACK
f08lsf |  | BLAS/LAPACK
f08mdf | NAG | BLAS/LAPACK
f08mef | NAG | BLAS/LAPACK
f08msf | NAG | BLAS/LAPACK
f08naf | NAG | BLAS/LAPACK
f08nbf | NAG | BLAS/LAPACK
f08nef | NAG | BLAS/LAPACK
f08nff | NAG | BLAS/LAPACK
f08ngf | NAG | BLAS/LAPACK
f08nhf |  | BLAS/LAPACK
f08njf |  | BLAS/LAPACK
f08nnf | NAG | BLAS/LAPACK
f08npf | NAG | BLAS/LAPACK
f08nsf |  | BLAS/LAPACK
f08ntf | NAG | BLAS/LAPACK
f08nuf | NAG | BLAS/LAPACK
f08nvf |  | BLAS/LAPACK
f08nwf |  | BLAS/LAPACK
f08paf | NAG | BLAS/LAPACK
f08pbf | NAG | BLAS/LAPACK
f08pef | NAG | BLAS/LAPACK
f08pkf | NAG | BLAS/LAPACK
f08pnf | NAG | BLAS/LAPACK
f08ppf | NAG | BLAS/LAPACK
f08psf | NAG | BLAS/LAPACK
f08pxf | NAG | BLAS/LAPACK
f08qff |  | BLAS/LAPACK
f08qgf |  | BLAS/LAPACK
f08qhf |  | BLAS/LAPACK
f08qkf |  | BLAS/LAPACK
f08qlf |  | BLAS/LAPACK
f08qtf |  | BLAS/LAPACK
f08quf |  | BLAS/LAPACK
f08qvf |  | BLAS/LAPACK
f08qxf |  | BLAS/LAPACK
f08qyf |  | BLAS/LAPACK
f08raf | NAG | BLAS/LAPACK
f08rnf | NAG | BLAS/LAPACK
f08saf | NAG | BLAS/LAPACK
f08sbf | NAG | BLAS/LAPACK
f08scf | NAG | BLAS/LAPACK
f08sef |  | BLAS/LAPACK
f08snf | NAG | BLAS/LAPACK
f08spf | NAG | BLAS/LAPACK
f08sqf | NAG | BLAS/LAPACK
f08ssf |  | BLAS/LAPACK
f08taf | NAG | BLAS/LAPACK
f08tbf | NAG | BLAS/LAPACK
f08tcf | NAG | BLAS/LAPACK
f08tef |  | BLAS/LAPACK
f08tnf | NAG | BLAS/LAPACK
f08tpf | NAG | BLAS/LAPACK
f08tqf | NAG | BLAS/LAPACK
f08tsf |  | BLAS/LAPACK
f08uaf | NAG | BLAS/LAPACK
f08ubf | NAG | BLAS/LAPACK
f08ucf | NAG | BLAS/LAPACK
f08uef |  | BLAS/LAPACK
f08uff |  | BLAS/LAPACK
f08unf | NAG | BLAS/LAPACK
f08upf | NAG | BLAS/LAPACK
f08uqf | NAG | BLAS/LAPACK
f08usf |  | BLAS/LAPACK
f08utf |  | BLAS/LAPACK
f08vaf |  | BLAS/LAPACK
f08vcf | NAG | BLAS/LAPACK
f08vef |  | BLAS/LAPACK
f08vgf | NAG | BLAS/LAPACK
f08vnf |  | BLAS/LAPACK
f08vqf | NAG | BLAS/LAPACK
f08vsf |  | BLAS/LAPACK
f08vuf | NAG | BLAS/LAPACK
f08waf | NAG | BLAS/LAPACK
f08wbf | NAG | BLAS/LAPACK
f08wcf | NAG | BLAS/LAPACK
f08wef |  | BLAS/LAPACK
f08wff |  | BLAS/LAPACK
f08whf |  | BLAS/LAPACK
f08wjf |  | BLAS/LAPACK
f08wnf | NAG | BLAS/LAPACK
f08wpf | NAG | BLAS/LAPACK
f08wqf | NAG | BLAS/LAPACK
f08wsf |  |
f08wtf |  | BLAS/LAPACK
f08wvf |  | BLAS/LAPACK
f08wwf |  | BLAS/LAPACK
f08xaf | NAG | BLAS/LAPACK
f08xbf | NAG | BLAS/LAPACK
f08xcf | NAG | BLAS/LAPACK
f08xef |  | BLAS/LAPACK
f08xnf | NAG | BLAS/LAPACK
f08xpf | NAG | BLAS/LAPACK
f08xqf | NAG | BLAS/LAPACK
f08xsf |  | BLAS/LAPACK
f08yef |  | BLAS/LAPACK
f08yff |  | BLAS/LAPACK
f08ygf |  | BLAS/LAPACK
f08yhf |  | BLAS/LAPACK
f08ykf |  | BLAS/LAPACK
f08ylf |  | BLAS/LAPACK
f08ysf |  | BLAS/LAPACK
f08ytf |  |
f08yuf |  | BLAS/LAPACK
f08yvf |  | BLAS/LAPACK
f08yxf |  | BLAS/LAPACK
f08yyf |  | BLAS/LAPACK
f08zaf | NAG | BLAS/LAPACK
f08zbf | NAG | BLAS/LAPACK
f08zef | NAG | BLAS/LAPACK
f08zff | NAG | BLAS/LAPACK
f08znf | NAG | BLAS/LAPACK
f08zpf | NAG | BLAS/LAPACK
f08zsf | NAG | BLAS/LAPACK
f08ztf | NAG | BLAS/LAPACK
f11bdf |  |
f11bef | NAG | BLAS/LAPACK
f11bff |  |
f11brf |  |
f11bsf | NAG | BLAS/LAPACK
f11btf |  |
f11daf |  |
f11dbf |  |
f11dcf | NAG | BLAS/LAPACK
f11ddf |  |
f11def | NAG | BLAS/LAPACK
f11dff | NAG |
f11dgf | NAG | BLAS/LAPACK
f11dkf | NAG | BLAS/LAPACK
f11dnf |  |
f11dpf |  |
f11dqf | NAG | BLAS/LAPACK
f11drf |  |
f11dsf | NAG | BLAS/LAPACK
f11dtf | NAG |
f11duf | NAG | BLAS/LAPACK
f11dxf | NAG | BLAS/LAPACK
f11gdf |  |
f11gef | NAG | BLAS/LAPACK
f11gff |  |
f11grf |  |
f11gsf | NAG | BLAS/LAPACK
f11gtf |  |
f11jaf |  | BLAS/LAPACK
f11jbf |  |
f11jcf | NAG | BLAS/LAPACK
f11jdf |  |
f11jef | NAG | BLAS/LAPACK
f11jnf |  | BLAS/LAPACK
f11jpf |  |
f11jqf | NAG | BLAS/LAPACK
f11jrf |  |
f11jsf | NAG | BLAS/LAPACK
f11mdf | NAG |
f11mef | NAG | BLAS/LAPACK
f11mff | NAG | BLAS/LAPACK
f11mgf |  | BLAS/LAPACK
f11mhf | NAG | BLAS/LAPACK
f11mkf | NAG |
f11mlf |  |
f11mmf |  |
f11xaf | NAG | BLAS/LAPACK
f11xef | NAG | BLAS/LAPACK
f11xnf | NAG | BLAS/LAPACK
f11xsf | NAG | BLAS/LAPACK
f11zaf |  |
f11zbf |  |
f11znf |  |
f11zpf |  |
f12aaf |  |
f12abf | NAG | BLAS/LAPACK
f12acf |  | BLAS/LAPACK
f12adf |  |
f12aef |  |
f12aff |  |
f12agf | NAG | BLAS/LAPACK
f12anf |  |
f12apf | NAG | BLAS/LAPACK
f12aqf |  | BLAS/LAPACK
f12arf |  |
f12asf |  |
f12atf |  |
f12auf | NAG | BLAS/LAPACK
f12faf |  |
f12fbf | NAG | BLAS/LAPACK
f12fcf | NAG | BLAS/LAPACK
f12fdf |  |
f12fef |  |
f12fff |  |
f12fgf | NAG | BLAS/LAPACK
f16dlf |  |
f16dnf |  |
f16dpf |  |
f16dqf |  |
f16drf |  |
f16eaf |  |
f16ecf |  | BLAS/LAPACK
f16ehf |  |
f16elf |  |
f16gcf |  | BLAS/LAPACK
f16ghf |  |
f16glf |  |
f16jnf |  |
f16jpf |  |
f16jqf |  |
f16jrf |  |
f16jsf |  |
f16jtf |  |
g01abf |  |
g01adf |  |
g01aef |  |
g01aff |  |
g01agf | NAG |
g01ahf | NAG |
g01ajf |  |
g01alf |  |
g01amf |  |
g01anf | NAG |
g01apf | NAG |
g01arf | NAG |
g01asf |  |
g01atf | NAG |
g01auf |  |
g01bjf |  |
g01bkf |  |
g01blf |  |
g01daf |  |
g01dbf |  |
g01dcf |  |
g01ddf |  |
g01dhf | NAG |
g01eaf |  |
g01ebf |  |
g01ecf |  |
g01edf |  |
g01eef |  |
g01eff |  |
g01emf |  |
g01epf |  |
g01erf |  |
g01etf |  |
g01euf |  |
g01ewf |  |
g01eyf |  |
g01ezf |  |
g01faf |  |
g01fbf |  |
g01fcf |  |
g01fdf |  |
g01fef |  |
g01fff |  |
g01fmf |  |
g01ftf |  |
g01gbf |  |
g01gcf |  |
g01gdf |  |
g01gef |  |
g01haf |  |
g01hbf |  |
g01hcf |  |
g01hdf |  |
g01jcf |  |
g01jdf | NAG |
g01kaf |  |
g01kff |  |
g01kkf |  |
g01kqf |  |
g01lbf | NAG | BLAS/LAPACK
g01mbf |  |
g01mtf |  |
g01muf |  |
g01naf |  | BLAS/LAPACK
g01nbf |  | BLAS/LAPACK
g01ptf |  |
g01qtf |  |
g01rtf |  |
g01saf |  |
g01sbf |  |
g01scf |  |
g01sdf |  |
g01sef |  |
g01sff |  |
g01sjf |  |
g01skf |  |
g01slf |  |
g01taf |  |
g01tbf |  |
g01tcf |  |
g01tdf |  |
g01tef |  |
g01tff |  |
g01waf | NAG | BLAS/LAPACK
g01zuf |  |
g02aaf | NAG | BLAS/LAPACK
g02abf | NAG | BLAS/LAPACK
g02aef | NAG | BLAS/LAPACK
g02ajf | NAG | BLAS/LAPACK
g02anf | NAG | BLAS/LAPACK
g02apf | NAG | BLAS/LAPACK
g02baf | NAG |
g02bbf |  |
g02bcf |  |
g02bdf | NAG |
g02bef |  |
g02bff |  |
g02bgf |  |
g02bhf |  |
g02bjf |  |
g02bkf |  |
g02blf |  |
g02bmf |  |
g02bnf | NAG |
g02bpf | NAG |
g02bqf | NAG |
g02brf | NAG |
g02bsf |  |
g02btf |  |
g02buf |  |
g02bwf |  |
g02bxf |  | BLAS/LAPACK
g02byf | NAG | BLAS/LAPACK
g02bzf |  | BLAS/LAPACK
g02caf |  |
g02cbf |  |
g02ccf |  |
g02cdf |  |
g02cef |  |
g02cff |  |
g02cgf | NAG | BLAS/LAPACK
g02chf | NAG | BLAS/LAPACK
g02daf | NAG | BLAS/LAPACK
g02dcf |  | BLAS/LAPACK
g02ddf | NAG | BLAS/LAPACK
g02def | NAG | BLAS/LAPACK
g02dff |  | BLAS/LAPACK
g02dgf | NAG | BLAS/LAPACK
g02dkf | NAG | BLAS/LAPACK
g02dnf |  | BLAS/LAPACK
g02eaf | NAG | BLAS/LAPACK
g02ecf |  |
g02eef | NAG | BLAS/LAPACK
g02eff |  |
g02faf |  |
g02fcf |  |
g02gaf | NAG | BLAS/LAPACK
g02gbf | NAG | BLAS/LAPACK
g02gcf | NAG | BLAS/LAPACK
g02gdf | NAG | BLAS/LAPACK
g02gkf | NAG | BLAS/LAPACK
g02gnf |  | BLAS/LAPACK
g02gpf |  | BLAS/LAPACK
g02haf | NAG | BLAS/LAPACK
g02hbf |  | BLAS/LAPACK
g02hdf | NAG | BLAS/LAPACK
g02hff | NAG | BLAS/LAPACK
g02hkf | NAG | BLAS/LAPACK
g02hlf |  | BLAS/LAPACK
g02hmf |  | BLAS/LAPACK
g02jaf | NAG | BLAS/LAPACK
g02jbf | NAG | BLAS/LAPACK
g02jcf |  |
g02jdf | NAG | BLAS/LAPACK
g02jef | NAG | BLAS/LAPACK
g02kaf | NAG | BLAS/LAPACK
g02kbf | NAG | BLAS/LAPACK
g02laf |  | BLAS/LAPACK
g02lbf |  | BLAS/LAPACK
g02lcf | NAG | BLAS/LAPACK
g02ldf |  | BLAS/LAPACK
g02maf | NAG | BLAS/LAPACK
g02mbf | NAG | BLAS/LAPACK
g02mcf | NAG | BLAS/LAPACK
g02qff | NAG | BLAS/LAPACK
g02qgf | NAG | BLAS/LAPACK
g03aaf |  | BLAS/LAPACK
g03acf | NAG | BLAS/LAPACK
g03adf | NAG | BLAS/LAPACK
g03baf |  | BLAS/LAPACK
g03bcf |  | BLAS/LAPACK
g03bdf | NAG | BLAS/LAPACK
g03caf | NAG | BLAS/LAPACK
g03ccf |  | BLAS/LAPACK
g03daf | NAG | BLAS/LAPACK
g03dbf |  | BLAS/LAPACK
g03dcf |  | BLAS/LAPACK
g03eaf | NAG |
g03ecf | NAG |
g03eff |  |
g03ehf |  |
g03ejf |  |
g03faf | NAG | BLAS/LAPACK
g03fcf |  | BLAS/LAPACK
g03gaf | NAG | BLAS/LAPACK
g03zaf |  |
g04agf |  |
g04bbf | NAG | BLAS/LAPACK
g04bcf | NAG | BLAS/LAPACK
g04caf |  | BLAS/LAPACK
g04daf |  |
g04dbf |  |
g04eaf | NAG | BLAS/LAPACK
g05kff |  |
g05kgf |  |
g05ncf | NAG |
g05ndf | NAG |
g05nef | NAG |
g05pdf | NAG |
g05pef | NAG |
g05pff | NAG |
g05pgf | NAG |
g05phf | NAG |
g05pjf | NAG | BLAS/LAPACK
g05pmf | NAG |
g05pvf | NAG | BLAS/LAPACK
g05pwf | NAG | BLAS/LAPACK
g05pxf | NAG | BLAS/LAPACK
g05pyf | NAG | BLAS/LAPACK
g05pzf | NAG |
g05rcf | NAG | BLAS/LAPACK
g05rdf | NAG | BLAS/LAPACK
g05ref | NAG |
g05rff | NAG |
g05rgf | NAG |
g05rhf | NAG |
g05rjf | NAG |
g05rkf | NAG |
g05ryf | NAG | BLAS/LAPACK
g05rzf | NAG | BLAS/LAPACK
g05saf | NAG |
g05sbf | NAG |
g05scf | NAG |
g05sdf | NAG |
g05sef | NAG |
g05sff | NAG |
g05sgf | NAG |
g05shf | NAG |
g05sjf | NAG |
g05skf | NAG |
g05slf | NAG |
g05smf | NAG |
g05snf | NAG |
g05spf | NAG |
g05sqf | NAG |
g05srf | NAG |
g05ssf | NAG |
g05taf | NAG |
g05tbf | NAG |
g05tcf | NAG |
g05tdf | NAG |
g05tef | NAG |
g05tff | NAG |
g05tgf | NAG |
g05thf | NAG |
g05tjf | NAG |
g05tkf |  |
g05tlf | NAG |
g05xaf |  |
g05xbf | NAG | BLAS/LAPACK
g05xcf |  |
g05xdf | NAG | BLAS/LAPACK
g05xef | NAG |
g05yjf | NAG | BLAS/LAPACK
g05ykf | NAG | BLAS/LAPACK
g05ylf | NAG |
g05ymf | NAG |
g05ynf | NAG |
g05zmf | NAG | BLAS/LAPACK
g05znf | NAG | BLAS/LAPACK
g05zpf | NAG | BLAS/LAPACK
g05zqf | NAG | BLAS/LAPACK
g05zrf | NAG | BLAS/LAPACK
g05zsf | NAG | BLAS/LAPACK
g05ztf | NAG | BLAS/LAPACK
g07aaf |  |
g07abf |  |
g07bbf |  |
g07bef | NAG |
g07bff | NAG |
g07caf |  |
g07daf | NAG | BLAS/LAPACK
g07dbf | NAG | BLAS/LAPACK
g07dcf | NAG | BLAS/LAPACK
g07ddf | NAG |
g07eaf | NAG |
g07ebf | NAG | BLAS/LAPACK
g08aaf |  |
g08acf |  |
g08aef |  |
g08aff |  |
g08agf | NAG |
g08ahf |  |
g08ajf |  |
g08akf | NAG |
g08alf |  |
g08baf |  |
g08cbf | NAG |
g08ccf | NAG |
g08cdf | NAG |
g08cgf |  |
g08daf |  |
g08eaf |  | BLAS/LAPACK
g08ebf |  |
g08ecf |  |
g08edf |  |
g08raf | NAG | BLAS/LAPACK
g08rbf | NAG | BLAS/LAPACK
g10abf |  |
g10acf |  |
g10bbf | NAG | BLAS/LAPACK
g10caf |  | BLAS/LAPACK
g10zaf |  |
g11aaf |  |
g11baf |  |
g11bbf | NAG |
g11bcf | NAG |
g11caf | NAG | BLAS/LAPACK
g11saf | NAG | BLAS/LAPACK
g11sbf |  |
g12aaf |  |
g12abf | NAG | BLAS/LAPACK
g12baf | NAG | BLAS/LAPACK
g12zaf |  |
g13aaf |  |
g13abf | NAG | BLAS/LAPACK
g13acf |  |
g13adf | NAG | BLAS/LAPACK
g13aef | NAG | BLAS/LAPACK
g13aff | NAG | BLAS/LAPACK
g13agf |  |
g13ahf |  |
g13ajf | NAG | BLAS/LAPACK
g13asf | NAG | BLAS/LAPACK
g13auf |  |
g13baf | NAG | BLAS/LAPACK
g13bbf | NAG | BLAS/LAPACK
g13bcf | NAG | BLAS/LAPACK
g13bdf | NAG | BLAS/LAPACK
g13bef | NAG | BLAS/LAPACK
g13bgf |  |
g13bhf |  |
g13bjf | NAG | BLAS/LAPACK
g13caf | NAG | BLAS/LAPACK
g13cbf | NAG | BLAS/LAPACK
g13ccf | NAG | BLAS/LAPACK
g13cdf | NAG | BLAS/LAPACK
g13cef |  |
g13cff |  |
g13cgf | NAG | BLAS/LAPACK
g13dbf | NAG | BLAS/LAPACK
g13ddf | NAG | BLAS/LAPACK
g13djf | NAG | BLAS/LAPACK
g13dkf |  | BLAS/LAPACK
g13dlf |  | BLAS/LAPACK
g13dmf |  | BLAS/LAPACK
g13dnf | NAG | BLAS/LAPACK
g13dpf | NAG | BLAS/LAPACK
g13dsf | NAG | BLAS/LAPACK
g13dxf | NAG | BLAS/LAPACK
g13eaf | NAG | BLAS/LAPACK
g13ebf | NAG | BLAS/LAPACK
g13ejf |  | BLAS/LAPACK
g13ekf |  | BLAS/LAPACK
g13faf | NAG | BLAS/LAPACK
g13fbf |  |
g13fcf | NAG | BLAS/LAPACK
g13fdf |  |
g13fef | NAG | BLAS/LAPACK
g13fff |  |
g13fgf | NAG | BLAS/LAPACK
g13fhf |  |
g13mef | NAG | BLAS/LAPACK
g13mff | NAG | BLAS/LAPACK
g13mgf | NAG | BLAS/LAPACK
g13ndf | NAG |
g13nef | NAG |
h02bbf |  | BLAS/LAPACK
h02bff |  | BLAS/LAPACK
h02buf |  |
h02bvf |  |
h02bzf |  |
h02cbf | NAG | BLAS/LAPACK
h02ccf |  |
h02cdf |  |
h02cef | NAG | BLAS/LAPACK
h02cff |  |
h02cgf |  |
h02daf |  | BLAS/LAPACK
h02zkf | NAG |
h02zlf |  |
h03abf |  |
h03adf |  |
h03bbf | NAG |
h05aaf | NAG |
h05abf | NAG |
m01caf | NAG |
m01cbf | NAG |
m01ccf | NAG |
m01daf |  |
m01dbf |  |
m01dcf |  |
m01def |  |
m01dff |  |
m01djf |  |
m01dkf |  |
m01dzf |  |
m01eaf |  |
m01ebf |  |
m01ecf |  |
m01edf |  |
m01naf |  |
m01nbf |  |
m01ncf |  |
m01zaf |  |
m01zbf |  |
m01zcf |  |
s01baf |  |
s01eaf |  |
s07aaf |  |
s09aaf |  |
s09abf |  |
s10aaf |  |
s10abf |  |
s10acf |  |
s11aaf |  |
s11abf |  |
s11acf |  |
s13aaf |  |
s13acf |  |
s13adf |  |
s14aaf |  |
s14abf |  |
s14acf |  |
s14adf |  |
s14aef |  |
s14aff |  |
s14agf |  |
s14ahf |  |
s14baf |  |
s14cbf |  |
s14ccf |  |
s15abf |  |
s15acf |  |
s15adf |  |
s15aef |  |
s15aff |  |
s15agf |  |
s15ddf |  |
s17acf |  |
s17adf |  |
s17aef |  |
s17aff |  |
s17agf |  |
s17ahf |  |
s17ajf |  |
s17akf |  |
s17alf |  |
s17aqf |  |
s17arf |  |
s17asf |  |
s17atf |  |
s17auf |  |
s17avf |  |
s17awf |  |
s17axf |  |
s17dcf |  |
s17def |  |
s17dgf |  |
s17dhf |  |
s17dlf |  |
s18acf |  |
s18adf |  |
s18aef |  |
s18aff |  |
s18aqf |  |
s18arf |  |
s18asf |  |
s18atf |  |
s18ccf |  |
s18cdf |  |
s18cef |  |
s18cff |  |
s18cqf |  |
s18crf |  |
s18csf |  |
s18ctf |  |
s18dcf |  |
s18def |  |
s18gkf |  |
s19aaf |  |
s19abf |  |
s19acf |  |
s19adf |  |
s19anf |  |
s19apf |  |
s19aqf |  |
s19arf |  |
s20acf |  |
s20adf |  |
s20aqf |  |
s20arf |  |
s21baf |  |
s21bbf |  |
s21bcf |  |
s21bdf |  |
s21bef |  |
s21bff |  |
s21bgf |  |
s21bhf |  |
s21bjf |  |
s21caf |  |
s21cbf |  |
s21ccf |  |
s21daf |  |
s22aaf |  |
s22baf | NAG | BLAS/LAPACK
s22bbf | NAG | BLAS/LAPACK
s30aaf | NAG |
s30abf | NAG |
s30baf | NAG |
s30bbf | NAG |
s30caf | NAG |
s30cbf | NAG |
s30ccf | NAG |
s30cdf | NAG |
s30faf | NAG |
s30jaf | NAG | BLAS/LAPACK
s30jbf | NAG |
s30naf | NAG |
s30nbf | NAG |
s30ncf | NAG |
s30qcf | NAG |
s30saf | NAG |
s30sbf | NAG |
x01aaf |  |
x01abf |  |
x02ahf |  |
x02ajf |  |
x02akf |  |
x02alf |  |
x02amf |  |
x02anf |  |
x02bbf |  |
x02bef |  |
x02bhf |  |
x02bjf |  |
x02bkf |  |
x02blf |  |
x03aaf |  |
x03abf |  |
x04aaf |  |
x04abf |  |
x04acf |  |
x04adf |  |
x04baf |  |
x04bbf |  |
x04caf |  |
x04cbf |  |
x04ccf |  |
x04cdf |  |
x04cef |  |
x04cff |  |
x04daf |  |
x04dbf |  |
x04dcf |  |
x04ddf |  |
x04def |  |
x04dff |  |
x04eaf |  |
x04ebf |  |
x05aaf |  |
x05abf |  |
x05acf |  |
x05baf |  |
x06aaf |  |
x06abf |  |
x06acf |  |
x06adf |  |
x06aff |  |
x06agf |  |
x06ahf |  |
x06xaf |  |
x07aaf |  |
x07abf |  |
x07baf |  |
x07bbf |  |
x07caf |  |
x07cbf |  |
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


Thread Unsafe Routines : NAG Library, Mark 26

NAG Library

Thread Unsafe Routines

Most routines in the NAG Library are thread safe, however there are some routines that are not thread safe as they use global variables (such as module variables, common blocks or variables with the SAVE attribute). See Section 3.12.1 in How to Use the NAG Library and its Documentation for further information.
Routine Name | Description
D02GAF | nagf_ode_bvp_fd_nonlin_fixedbc Ordinary differential equations, boundary value problem, finite difference technique with deferred correction, simple nonlinear problem
D02GBF | nagf_ode_bvp_fd_lin_gen Ordinary differential equations, boundary value problem, finite difference technique with deferred correction, general linear problem
D02HAF | nagf_ode_bvp_shoot_bval Ordinary differential equations, boundary value problem, shooting and matching, boundary values to be determined
D02HBF | nagf_ode_bvp_shoot_genpar Ordinary differential equations, boundary value problem, shooting and matching, general parameters to be determined
D02JAF | nagf_ode_bvp_coll_nth Ordinary differential equations, boundary value problem, collocation and least squares, single nth-order linear equation
D02JBF | nagf_ode_bvp_coll_sys Ordinary differential equations, boundary value problem, collocation and least squares, system of first-order linear equations
D02LAF | nagf_ode_ivp_2nd_rkn Second-order ordinary differential equations, initial value problem, Runge–Kutta–Nystrom method
D02LXF | nagf_ode_ivp_2nd_rkn_setup Second-order ordinary differential equations, initial value problem, setup for
D02LYF | nagf_ode_ivp_2nd_rkn_diag Second-order ordinary differential equations, initial value problem, diagnostics for
D02LZF | nagf_ode_ivp_2nd_rkn_interp Second-order ordinary differential equations, initial value problem, interpolation for
D02MZF | nagf_ode_ivp_stiff_interp Ordinary differential equations, initial value problem, interpolation for D02M–N routines (all integration methods), natural interpolant
D02NBF | nagf_ode_ivp_stiff_exp_fulljac Explicit ordinary differential equations, stiff initial value problem, full Jacobian (comprehensive)
D02NCF | nagf_ode_ivp_stiff_exp_bandjac Explicit ordinary differential equations, stiff initial value problem, banded Jacobian (comprehensive)
D02NDF | nagf_ode_ivp_stiff_exp_sparjac Explicit ordinary differential equations, stiff initial value problem, sparse Jacobian (comprehensive)
D02NGF | nagf_ode_ivp_stiff_imp_fulljac Implicit/algebraic ordinary differential equations, stiff initial value problem, full Jacobian (comprehensive)
D02NHF | nagf_ode_ivp_stiff_imp_bandjac Implicit/algebraic ordinary differential equations, stiff initial value problem, banded Jacobian (comprehensive)
D02NJF | nagf_ode_ivp_stiff_imp_sparjac Implicit/algebraic ordinary differential equations, stiff initial value problem, sparse Jacobian (comprehensive)
D02NMF | nagf_ode_ivp_stiff_exp_revcom Explicit ordinary differential equations, stiff initial value problem (reverse communication, comprehensive)
D02NNF | nagf_ode_ivp_stiff_imp_revcom Implicit/algebraic ordinary differential equations, stiff initial value problem (reverse communication, comprehensive)
D02NSF | nagf_ode_ivp_stiff_fulljac_setup Ordinary differential equations, initial value problem, for use with D02M–N s, full Jacobian, linear algebra set up
D02NTF | nagf_ode_ivp_stiff_bandjac_setup Ordinary differential equations, initial value problem, for use with D02M–N s, banded Jacobian, linear algebra set up
D02NUF | nagf_ode_ivp_stiff_sparjac_setup Ordinary differential equations, initial value problem, for use with D02M–N s, sparse Jacobian, linear algebra set up
D02QFF | nagf_ode_ivp_adams_roots Ordinary differential equations, initial value problem, Adams' method with root-finding (direct communication, comprehensive)
D02QGF | nagf_ode_ivp_adams_roots_revcom Ordinary differential equations, initial value problem, Adams' method with root-finding (reverse communication, comprehensive)
D02QWF | nagf_ode_ivp_adams_setup Ordinary differential equations, initial value problem, setup for and
D02QXF | nagf_ode_ivp_adams_diag Ordinary differential equations, initial value problem, diagnostics for and
D02QYF | nagf_ode_ivp_adams_rootdiag Ordinary differential equations, initial value problem, root-finding diagnostics for and
D02QZF | nagf_ode_ivp_adams_interp Ordinary differential equations, initial value problem, interpolation for or
D02RAF | nagf_ode_bvp_fd_nonlin_gen Ordinary differential equations, general nonlinear boundary value problem, finite difference technique with deferred correction, continuation facility
D02SAF | nagf_ode_bvp_shoot_genpar_algeq Ordinary differential equations, boundary value problem, shooting and matching technique, subject to extra algebraic equations, general parameters to be determined
D02XKF | nagf_ode_ivp_stiff_c1_interp Ordinary differential equations, initial value problem, interpolation for D02M–N s, C1 interpolant
D02ZAF | nagf_ode_ivp_stiff_errest Ordinary differential equations, initial value problem, weighted norm of local error estimate for D02M–N s
D03PEF | nagf_pde_1d_parab_keller General system of first-order PDEs, method of lines, Keller box discretization, one space variable
D03PFF | nagf_pde_1d_parab_convdiff General system of convection-diffusion PDEs with source terms in conservative form, method of lines, upwind scheme using numerical flux function based on Riemann solver, one space variable
D03PKF | nagf_pde_1d_parab_dae_keller General system of first-order PDEs, coupled DAEs, method of lines, Keller box discretization, one space variable
D03PLF | nagf_pde_1d_parab_convdiff_dae General system of convection-diffusion PDEs with source terms in conservative form, coupled DAEs, method of lines, upwind scheme using numerical flux function based on Riemann solver, one space variable
D03PRF | nagf_pde_1d_parab_remesh_keller General system of first-order PDEs, coupled DAEs, method of lines, Keller box discretization, remeshing, one space variable
D03PSF | nagf_pde_1d_parab_convdiff_remesh General system of convection-diffusion PDEs, coupled DAEs, method of lines, upwind scheme, remeshing, one space variable
D03PUF | nagf_pde_1d_parab_euler_roe Roe's approximate Riemann solver for Euler equations in conservative form, for use with , and
D03PVF | nagf_pde_1d_parab_euler_osher Osher's approximate Riemann solver for Euler equations in conservative form, for use with , and
D03PWF | nagf_pde_1d_parab_euler_hll Modified HLL Riemann solver for Euler equations in conservative form, for use with , and
D03PXF | nagf_pde_1d_parab_euler_exact Exact Riemann solver for Euler equations in conservative form, for use with , and
D03RAF | nagf_pde_2d_gen_order2_rectangle General system of second-order PDEs, method of lines, finite differences, remeshing, two space variables, rectangular region
D03RBF | nagf_pde_2d_gen_order2_rectilinear General system of second-order PDEs, method of lines, finite differences, remeshing, two space variables, rectilinear region
E01SBF | nagf_interp_2d_scat_eval Interpolated values, evaluate interpolant computed by , two variables
G08EAF | nagf_nonpar_randtest_runs Performs the runs up or runs down test for randomness
G08EBF | nagf_nonpar_randtest_pairs Performs the pairs (serial) test for randomness
G08ECF | nagf_nonpar_randtest_triplets Performs the triplets test for randomness
G08EDF | nagf_nonpar_randtest_gaps Performs the gaps test for randomness
H02BBF | nagf_mip_ilp_dense Integer LP problem (dense)
H02BFF | nagf_mip_ilp_mpsx Interpret MPSX data file defining IP or LP problem, optimize and print solution
H02BVF | nagf_mip_ilp_print Print IP or LP solutions with user-specified names for rows and columns
H02CBF | nagf_mip_iqp_dense Integer QP problem (dense)
H02CCF | nagf_mip_iqp_dense_optfile Read values for from external file
H02CDF | nagf_mip_iqp_dense_optstr Supply values to
H02CEF | nagf_mip_iqp_sparse Integer LP or QP problem (sparse), using
H02CFF | nagf_mip_iqp_sparse_optfile Read values for from external file
H02CGF | nagf_mip_iqp_sparse_optstr Supply values to
X04AAF | nagf_file_set_unit_error Return or set unit number for error messages
X04ABF | nagf_file_set_unit_advisory Return or set unit number for advisory messages
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


Implementation-specific Details for Users : NAG Library, Mark 26

NAG Library

Implementation-specific Details for Users

The Library is available on many different computer systems. For each distinct system, an implementation of the Library is prepared by NAG, e.g., the Linux 64 (Intel® 64 / AMD64), GNU gfortran implementation. The implementation is distributed to sites as a tested compiled library.
An implementation is usually specific to a range of machines/operating systems (e.g., x86–64 architectures); it may also be specific to a particular Fortran compiler, or compiler option (such as for calling convention).
Essentially the same facilities are provided in all implementations of the Library, but, because of differences in arithmetic behaviour and in the compilation system, routines cannot be expected to give identical results on different systems, especially for sensitive numerical problems.
The documentation supports all implementations of the Library, with the help of a few simple conventions, and a small amount of implementation-dependent information, which is published in a separate Users' Note for each implementation (see Section 4.4 in How to Use the NAG Library and its Documentation).
Each implementation of the NAG Library is generally specific to a particular computing environment on which its operation has been tested and verified. In contrast, the NAG Library Manual is appropriate for all implementations of the Library at that Mark.
Any information that applies solely to a specific implementation is provided, together with the software, on the distribution medium. The Users' Note for your implementation is also available on the NAG web site.
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


H02BBF : NAG Library, Mark 26

H Chapter Contents
H Chapter Introduction
NAG Library Manual

NAG Library Routine Document

H02BBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
▸▿ 5 Arguments
5.1 Description of Printed Output
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

H02BBF solves ‘zero-one’, ‘general’, ‘mixed’ or ‘all’ integer programming problems using a branch and bound method. The routine may also be used to find either the first integer solution or the optimum integer solution. It is not intended for large sparse problems.

2 Specification

SUBROUTINE H02BBF ( ITMAX, MSGLVL, N, M, A, LDA, BL, BU, INTVAR, CVEC, MAXNOD, INTFST, MAXDPT, TOLIV, TOLFES, BIGBND, X, OBJMIP, IWORK, LIWORK, RWORK, LRWORK, IFAIL)
INTEGER | ITMAX, MSGLVL, N, M, LDA, INTVAR(N), MAXNOD, INTFST, MAXDPT, IWORK(LIWORK), LIWORK, LRWORK, IFAIL
REAL (KIND=nag_wp) | A(LDA,*), BL(N+M), BU(N+M), CVEC(N), TOLIV, TOLFES, BIGBND, X(N), OBJMIP, RWORK(LRWORK)

3 Description

H02BBF is capable of solving certain types of integer programming (IP) problems using a branch and bound (B&B) method, see Taha (1987). In order to describe these types of integer programs and to briefly state the B&B method, we define the following linear programming (LP) problem:
Minimize
F x=c 1x 1+c 2x 2+⋯+cnxn
subject to
∑j= 1 n a ijxj = ≤ ≥ bi,   i= 1,2,…,m
lj≤xj≤uj,  j=1,2,…,n (1)
If, in (1), it is required that (some or) all the variables take integer values, then the integer program is of type (mixed or) all general IP problem. If additionally, the integer variables are restricted to take only 0–1 values (i.e., lj=0 and uj=1) then the integer program is of type (mixed or all) zero-one IP problem.
The B&B method applies directly to these integer programs. The general idea of B&B (for a full description see Dakin (1965) or Mitra (1973)) is to solve the problem without the integral restrictions as an LP problem (first node). If in the optimal solution an integer variable xk takes a noninteger value xk*, two LP sub-problems are created by branching, imposing xk≤xk* and xk≥xk*+1 respectively, where xk* denotes the integer part of xk*. This method of branching continues until the first integer solution (bound) is obtained. The hanging nodes are then solved and investigated in order to prove the optimality of the solution. At each node, an LP problem is solved using E04MFF/E04MFA.

4 References

Dakin R J (1965) A tree search algorithm for mixed integer programming problems Comput. J. 8 250–255
Mitra G (1973) Investigation of some branch and bound strategies for the solution of mixed integer linear programs Math. Programming 4 155–170
Taha H A (1987) Operations Research: An Introduction Macmillan, New York

5 Arguments

1:   ITMAX – INTEGERInput/Output
On entry: an upper bound on the number of iterations for each LP problem.
On exit: unchanged if on entry ITMAX>0, else ITMAX=max 50,5×N+M.
2:   MSGLVL – INTEGERInput
On entry: the amount of printout produced by H02BBF, as indicated below (see Section 5.1 for a description of the printed output). All output is written to the current advisory message unit (as defined by X04ABF).
Value | Definition
0 | No output.
1 | The final IP solution only.
5 | One line of output for each node investigated and the final IP solution.
10 | The original LP solution (first node), one line of output for each node investigated and the final IP solution.
3:   N – INTEGERInput
On entry: n, the number of variables.
Constraint: N>0.
4:   M – INTEGERInput
On entry: m, the number of general linear constraints.
Constraint: M≥0.
5:   A LDA* – REAL (KIND=nag_wp) arrayInput
Note: the second dimension of the array A must be at least N if M>0 and at least 1 if M=0.
On entry: the ith row of A must contain the coefficients of the ith general constraint, for i=1,2,…,m.
If M=0 then the array A is not referenced.
6:   LDA – INTEGERInput
On entry: the first dimension of the array A as declared in the (sub)program from which H02BBF is called.
Constraint: LDA≥max 1,M.
7:   BL N+M – REAL (KIND=nag_wp) arrayInput
8:   BU N+M – REAL (KIND=nag_wp) arrayInput
On entry: BL must contain the lower bounds and BU the upper bounds, for all the constraints in the following order. The first n elements of each array must contain the bounds on the variables, and the next m elements the bounds for the general linear constraints (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set BL j≤-BIGBND and to specify a nonexistent upper bound (i.e., uj=+∞), set BU j≥BIGBND. To specify the jth constraint as an equality, set BL j=BU j=β, say, where β<BIGBND.
Constraints:
  • BL j≤BU j, for j=1,2,…,N+M;
  • if BL j=BU j=β, β<BIGBND.
9:   INTVAR N – INTEGER arrayInput
On entry: indicates which are the integer variables in the problem. For example, if xj is an integer variable then INTVAR j must be set to 1, and 0 otherwise.
Constraints:
  • INTVAR j=0 or 1, for j=1,2,…,N;
  • INTVAR j=1 for at least one value of j.
10:   CVEC N – REAL (KIND=nag_wp) arrayInput
On entry: the coefficients cj of the objective function F x=c 1x 1+c 2x 2+…+cnxn. The routine attempts to find a minimum of F x. If a maximum of F x is desired, CVEC j should be set to -cj, for j=1,2,…,n, so that the routine will find a minimum of -F x.
11:   MAXNOD – INTEGERInput
On entry: the maximum number of nodes that are to be searched in order to find a solution (optimum integer solution). If MAXNOD≤0 and INTFST≤0, then the B&B tree search is continued until all the nodes have been investigated.
12:   INTFST – INTEGERInput
On entry: specifies whether to terminate the B&B tree search after the first integer solution (if any) is obtained. If INTFST>0 then the B&B tree search is terminated at node k say, which contains the first integer solution. For MAXNOD>0 this applies only if k≤MAXNOD.
13:   MAXDPT – INTEGERInput
On entry: the maximum depth of the B&B tree used for branch and bound.
Suggested value: MAXDPT=3×N/2.
Constraint: MAXDPT≥2.
14:   TOLIV – REAL (KIND=nag_wp)Input/Output
On entry: the integer feasibility tolerance; i.e., an integer variable is considered to take an integer value if its violation does not exceed TOLIV. For example, if the integer variable xj is near unity then xj is considered to be integer only if 1-TOLIV≤xj≤1+TOLIV.
On exit: unchanged if on entry TOLIV>0.0, else TOLIV=10-5.
15:   TOLFES – REAL (KIND=nag_wp)Input/Output
On entry: the maximum acceptable absolute violation in each constraint at a ‘feasible’ point (feasibility tolerance); i.e., a constraint is considered satisfied if its violation does not exceed TOLFES.
On exit: unchanged if on entry TOLFES>0.0, else TOLFES=ε (where ε is the machine precision).
16:   BIGBND – REAL (KIND=nag_wp)Input/Output
On entry: the ‘infinite’ bound size in the definition of the problem constraints. More precisely, any upper bound greater than or equal to BIGBND will be regarded as +∞ and any lower bound less than or equal to -BIGBND will be regarded as -∞.
On exit: unchanged if on entry BIGBND>0.0, else BIGBND=1020.
17:   X N – REAL (KIND=nag_wp) arrayInput/Output
On entry: an initial estimate of the original LP solution.
On exit: with IFAIL=0, X contains a solution which will be an estimate of either the optimum integer solution or the first integer solution, depending on the value of INTFST. If IFAIL=9, then X contains a solution which will be an estimate of the best integer solution that was obtained by searching MAXNOD nodes.
18:   OBJMIP – REAL (KIND=nag_wp)Output
On exit: with IFAIL=0 or 9, OBJMIP contains the value of the objective function for the IP solution.
19:   IWORK LIWORK – INTEGER arrayCommunication Array
20:   LIWORK – INTEGERInput
On entry: the dimension of the array IWORK as declared in the (sub)program from which H02BBF is called.
Constraint: LIWORK≥25+N+M×MAXDPT+5×N+M+4.
21:   RWORK LRWORK – REAL (KIND=nag_wp) arrayCommunication Array
22:   LRWORK – INTEGERInput
On entry: the dimension of the array RWORK as declared in the (sub)program from which H02BBF is called.
Constraint: LRWORK≥MAXDPT×N+1+2× min N,M+1 2 +14×N+12×M.
If MSGLVL>0, the amounts of workspace provided and required (with MAXDPT=3×N/2) are printed. As an alternative to computing MAXDPT, LIWORK and LRWORK from the formulas given above, you may prefer to obtain appropriate values from the output of a preliminary run with the values of MAXDPT, LIWORK and LRWORK set to 1. If however only LIWORK and LRWORK are set to 1, then the appropriate values of these arguments for the given value of MAXDPT will be computed and printed unless MAXDPT<2. In both cases H02BBF will then terminate with IFAIL=6.
23:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if IFAIL≠0 on exit, the recommended value is -1. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

5.1 Description of Printed Output

The level of printed output from H02BBF is controlled by you (see the description of MSGLVL in Section 5).
When MSGLVL>0, the summary printout at the end of execution of H02BBF includes a listing of the status of every variable and constraint. Note that default names are assigned to all variables and constraints. The following describes the printout for each variable.
Varbl | gives the name (V) and index j, for j=1,2,…,n, of the variable.
State | gives the state of the variable (FR if neither bound is in the working set, EQ if a fixed variable, LL if on its lower bound, UL if on its upper bound, TF if temporarily fixed at its current value). If Value lies outside the upper or lower bounds by more than the Feasibility Tolerance, State will be ++ or -- respectively.
Value | is the value of the variable at the final iterate.
Lower Bound | is the lower bound specified for the variable. (None indicates that BL j≤-BIGBND.) Note that if INTVAR j=1, then the printed value of Lower Bound for the jth variable may not be the same as that originally supplied in BL j.
Upper Bound | is the upper bound specified for the variable. (None indicates that BU j≥BIGBND.) Note that if INTVAR j=1, then the printed value of Upper Bound for the jth variable may not be the same as that originally supplied in BU j.
Lagr Mult | is the value of the Lagrange-multiplier for the associated bound constraint. This will be zero if State is FR or TF. If x is optimal, the multiplier should be non-negative if State is LL, and non-positive if State is UL.
Residual | is the difference between the variable Value and the nearer of its bounds BL j and BU j.
The meaning of the printout for general constraints is the same as that given above for variables, with ‘variable’ replaced by ‘constraint’, BL j and BU j are replaced by BL n+j and BU n+j respectively, and with the following change in the heading.
L Con gives the name (L) and index j, for j=1,2,…,m, of the constraint.
When MSGLVL>1, the summary printout at the end of every node during the execution of H02BBF is a listing of the outcome of forcing an integer variable with a noninteger value to take a value within its specified lower and upper bounds.
Node No | is the current node number of the B&B tree being investigated.
Parent Node | is the parent node number of the current node.
Obj Value | is the final objective function value. If a node does not have a feasible solution then No Feas Soln is printed instead of the objective function value. If a node whose optimum solution exceeds the best integer solution so far is encountered (i.e., it does not pay to explore the sub-problem any further), then its objective function value is printed together with a CO (Cut Off).
Varbl Chosen | is the index of the integer variable chosen for branching.
Value Before | is the noninteger value of the integer variable chosen.
Lower Bound | is the lower bound value that the integer variable is allowed to take.
Upper Bound | is the upper bound value that the integer variable is allowed to take.
Value After | is the value of the integer variable after the current optimization.
Depth | is the depth of the B&B tree at the current node.

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Note: H02BBF may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the routine:
IFAIL=1
No feasible integer point was found, i.e., it was not possible to satisfy all the integer variables to within the integer feasibility tolerance (determined by TOLIV). Increase TOLIV and rerun H02BBF.
IFAIL=2
The original LP solution appears to be unbounded. This value of IFAIL implies that a step as large as BIGBND would have to be taken in order to continue the algorithm (see Section 9).
IFAIL=3
No feasible point was found for the original LP problem, i.e., it was not possible to satisfy all the constraints to within the feasibility tolerance (determined by TOLFES). If the data for the constraints are accurate only to the absolute precision σ, you should ensure that the value of the feasibility tolerance is greater than σ. For example, if all elements of A are of order unity and are accurate only to three decimal places, the feasibility tolerance should be at least 10-3 (see Section 9).
IFAIL=4
The maximum number of iterations (determined by ITMAX) was reached before normal termination occurred for the original LP problem (see Section 9).
IFAIL=5
Not used by this routine.
IFAIL=6
An input argument is invalid.
IFAIL=7
The IP solution reported is not the optimum IP solution. In other words, the B&B tree search for at least one of the branches had to be terminated since an LP sub-problem in the branch did not have a solution (see Section 9).
IFAIL=8
The maximum depth of the B&B tree used for branch and bound (determined by MAXDPT) is too small. Increase MAXDPT (along with LIWORK and/or LRWORK if appropriate) and rerun H02BBF.
IFAIL=9
The IP solution reported is the best IP solution for the number of nodes (determined by MAXNOD) investigated in the B&B tree.
IFAIL=10
No feasible integer point was found for the number of nodes (determined by MAXNOD) investigated in the B&B tree.
IFAIL=11
Although the workspace sizes are sufficient to meet the documented restriction, they are not sufficiently large to accommodate an internal partition of the workspace that meets the requirements of the problem. Increase the workspace sizes.
The maximum depth of the B&B tree used for branch and bound (determined by MAXDPT) is too small. Increase MAXDPT (along with LIWORK and/or LRWORK if appropriate) and rerun H02BBF.
Overflow
It may be possible to avoid the difficulty by increasing the magnitude of the feasibility tolerance (TOLFES) and rerunning the program. If the message recurs even after this change, see Section 9.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

H02BBF implements a numerically stable active set strategy and returns solutions that are as accurate as the condition of the problem warrants on the machine.

8 Parallelism and Performance

H02BBF is not thread safe and should not be called from a multithreaded user program. Please see Section 3.12.1 in How to Use the NAG Library and its Documentation for more information on thread safety.
H02BBF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

The original LP problem may not have an optimum solution, i.e., H02BBF terminates with IFAIL=2, 3 or 4 or overflow may occur. In this case, you are recommended to relax the integer restrictions of the problem and try to find the optimum LP solution by using E04MFF/E04MFA instead.
In the B&B method, it is possible for an LP sub-problem to terminate without finding a solution. This may occur due to the number of iterations exceeding the maximum allowed. Therefore the B&B tree search for that particular branch cannot be continued. Thus the returned solution may not be optimal. (IFAIL=7). For the second and unlikely case, a solution could not be found despite a second attempt at an LP solution.

10 Example

This example solves the integer programming problem:
maximize
F x=3 x 1+4 x 2
subject to the bounds
x 1≥ 0 x 2≥ 0
and to the general constraints
2 x 1+5 x 2≤15 2 x 1-2 x 2≤5 3 x 1+2 x 2≥5
where x 1 and x 2 are integer variables.
The initial point, which is feasible, is
x 0=1,1 T,
and F x 0=7.
The optimal solution is
x*=2,2 T,
and F x*=14.
Note that maximizing F x is equivalent to minimizing -F x.

10.1 Program Text

Program Text (h02bbfe.f90)

10.2 Program Data

Program Data (h02bbfe.d)

10.3 Program Results

Program Results (h02bbfe.r)

H Chapter Contents
H Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


H02BFF : NAG Library, Mark 26

H Chapter Contents
H Chapter Introduction
NAG Library Manual

NAG Library Routine Document

H02BFF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

H02BFF solves linear or integer programming problems specified in MPSX input format. It is not intended for large sparse problems.

2 Specification

SUBROUTINE H02BFF ( INFILE, MAXN, MAXM, OPTIM, XBLDEF, XBUDEF, MAXDPT, MSGLVL, N, M, X, CRNAME, IWORK, LIWORK, RWORK, LRWORK, IFAIL)
INTEGER | INFILE, MAXN, MAXM, MAXDPT, MSGLVL, N, M, IWORK(LIWORK), LIWORK, LRWORK, IFAIL
REAL (KIND=nag_wp) | XBLDEF, XBUDEF, X(MAXN), RWORK(LRWORK)
CHARACTER(3) | OPTIM
CHARACTER(8) | CRNAME(MAXN+MAXM)

3 Description

H02BFF solves linear programming (LP) or integer programming (IP) problems specified in MPSX (see IBM (1971)) input format. It calls either E04MFF/E04MFA (to solve an LP problem) or H02BBF and H02BZF (to solve an IP problem); these routines are designed to solve problems of the form
minimize x∈Rn cT x  subject to  l≤ x Ax ≤u
where c is an n-element vector and A is an m by n matrix (i.e., there are n variables and m general linear constraints). H02BBF is used if at least one of the variables is restricted to take an integer value at the optimum solution. The document for H02BUF should be consulted for a detailed description of the MPSX format.
In the MPSX data file the first free row, that is a row defined with the row type N, is taken as the objective row. Similarly, if there are more than one RHS, RANGES or BOUNDS sets, then the first set is used for the optimization. H02BFF also prints the solution to the problem using the row and column names specified in the MPSX data file (by calling H02BVF).

4 References

IBM (1971) MPSX – Mathematical programming system Program Number 5734 XM4 IBM Trade Corporation, New York

5 Arguments

1:   INFILE – INTEGERInput
On entry: the unit number associated with the MPSX data file.
Constraint: 0≤INFILE≤99.
2:   MAXN – INTEGERInput
On entry: an upper limit for the number of variables in the problem.
Constraint: MAXN≥1.
3:   MAXM – INTEGERInput
On entry: an upper limit for the number of constraints (including the objective) in the problem.
Constraint: MAXM≥1.
4:   OPTIM – CHARACTER(3)Input
On entry: specifies the direction of the optimization. OPTIM must be set to 'MIN' for minimization and to 'MAX' for maximization.
Constraint: OPTIM='MIN' or 'MAX'.
5:   XBLDEF – REAL (KIND=nag_wp)Input
On entry: the default lower bound to be used for the variables in the problem when none is specified in the BOUNDS section of the MPSX data file. For a standard LP or IP problem XBLDEF would normally be set to zero.
6:   XBUDEF – REAL (KIND=nag_wp)Input
On entry: the default upper bound to be used for the variables in the problem when none is specified in the BOUNDS section of the MPSX data file. For a standard LP or IP problem XBUDEF would normally be set to ‘infinity’ (i.e., XBUDEF≥1020).
Constraint: XBUDEF≥XBLDEF.
7:   MAXDPT – INTEGERInput
On entry: for an IP problem, MAXDPT must specify the maximum depth of the branch and bound tree.
Constraint: MAXDPT≥2.
For an LP problem, MAXDPT is not referenced
8:   MSGLVL – INTEGERInput
On entry: the amount of printout produced by E04MFF/E04MFA or H02BBF, as indicated below. For a description of the printed output see Section 9.2 in E04MFF/E04MFA or Section 5.1 in H02BBF (as appropriate). All output is written to the current advisory message unit (as defined by X04ABF).
For an LP problem (E04MFF/E04MFA):
Value | Definition
0 | No output.
1 | The final solution only.
5 | One line of output for each iteration (no printout of the final solution).
10 | The final solution and one line of output for each iteration.
For an IP problem (H02BBF):
Value | Definition
0 | No output.
1 | The final IP solution only.
5 | One line of output for each node investigated and the final IP solution.
10 | The original LP solution (first node) with dummy names for the rows and columns, one line of output for each node investigated and the final IP solution with MPSX names for the rows and columns.
9:   N – INTEGEROutput
On exit: n, the actual number of variables in the problem.
10:   M – INTEGEROutput
On exit: m, the actual number of general linear constraints in the problem.
11:   X MAXN – REAL (KIND=nag_wp) arrayOutput
On exit: the solution to the problem, stored in X 1,X 2,…,X N. X i is the value of the variable whose MPSX name is stored in CRNAME i, for i=1,2,…,N.
12:   CRNAME MAXN+MAXM – CHARACTER(8) arrayOutput
On exit: the first N elements contain the MPSX names for the variables in the problem.
13:   IWORK LIWORK – INTEGER arrayOutput
On exit: the first (N+M) elements contain ISTATE (the status of the constraints in the working set at the solution). Further details can be found in Section 5 in E04MFF/E04MFA or H02BZF (as appropriate).
14:   LIWORK – INTEGERInput
On entry: the dimension of the array IWORK as declared in the (sub)program from which H02BFF is called.
Constraints:
  • for an LP problem, LIWORK≥4×MAXN+MAXM+3;
  • for an IP problem, LIWORK≥25+MAXN+MAXM×MAXDPT+7×MAXN+2× MAXM+4.
15:   RWORK LRWORK – REAL (KIND=nag_wp) arrayOutput
On exit: the first (N+M) elements contain BL (the lower bounds), the next (N+M) elements contain BU (the upper bounds) and the next (N+M) elements contain CLAMDA (the Lagrange-multipliers). Further details can be found in Section 5 in E04MFF/E04MFA or H02BZF (as appropriate). Note that for an IP problem the contents of BL and BU may not be the same as those originally specified in the MPSX data file and/or via the arguments XBLDEF and XBUDEF.
16:   LRWORK – INTEGERInput
On entry: the dimension of the array RWORK as declared in the (sub)program from which H02BFF is called.
Constraints:
  • for an LP problem, LRWORK≥2×MIN MAXN,MAXM+1 2+MAXM×MAXN+ 12×MAXN+9×MAXM;
  • for an IP problem,
    LRWORK≥MAXDPT×MAXN+1+2×MIN MAXN,MAXM+1 2+MAXM× MAXN+19×MAXN+15×MAXM.
17:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=i and IFAIL<0
Either MAXM and/or MAXN are too small or the MPSX data file is nonstandard and/or corrupt. This corresponds to IFAIL=-i in Section 6 in H02BUF.
IFAIL=1
X is a weak local minimum. This means that the solution is not unique.
IFAIL=2
The solution appears to be unbounded. This value of IFAIL implies that a step as large as XBUDEF would have to be taken in order to continue the algorithm. See Section 9.
IFAIL=3
No feasible point was found, i.e., it was not possible to satisfy all the constraints to within the feasibility tolerance (defined internally as machine precision). See Section 9.
IFAIL=4
The maximum number of iterations (defined internally as max 50,5 n+m) was reached before normal termination occurred. See Section 9.
IFAIL=5
An input argument is invalid. Refer to the printed output to determine which argument must be redefined.
IFAIL=6 (E04MFF/E04MFA or H02BBF)
A serious error has occurred in an internal call to one of the specified routines. Check all subroutine calls and array dimensions.
For an IP problem only:
IFAIL=7
The solution returned may not be optimal. See Section 9.
IFAIL=8
MAXDPT is too small. Try increasing its value (along with that of LIWORK and/or LRWORK if appropriate) and rerun H02BFF.
IFAIL=9
No feasible integer point was found, i.e., it was not possible to satisfy all the integer variables to within the integer feasibility tolerance (defined internally as 10-5). See Section 9.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

H02BFF implements a numerically stable active set strategy and returns solutions that are as accurate as the condition of the problem allows on the machine.

8 Parallelism and Performance

H02BFF is not thread safe and should not be called from a multithreaded user program. Please see Section 3.12.1 in How to Use the NAG Library and its Documentation for more information on thread safety.
H02BFF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

For an LP problem only:
  • If IFAIL=2 on exit, you can obtain more information by making separate calls to H02BUF, E04MFF/E04MFA and H02BVF (in that order). Note that this will (by default) cause the final LP solution to be printed twice on the current advisory message unit (see X04ABF), once with dummy names for the rows and columns and once with user-supplied names. To suppress the printout of the final LP solution with dummy names for the rows and columns, include the statement
    CALL E04MHF/E04MHA(' Print Level = 5 ')
    prior to calling E04MFF/E04MFA.
  • If IFAIL=3 on exit, you are recommended to reset the value of the feasibility tolerance and rerun H02BFF. (Further advice is given under the description of IFAIL=3 in Section 6 in E04MFF/E04MFA.) For example, to reset the value of the feasibility tolerance to 0.01, include the statement
    CALL E04MHF/E04MHA(' Feasibility Tolerance = 0.01 ')
    prior to calling H02BFF.
  • If IFAIL=4 on exit, you are recommended to increase the maximum number of iterations allowed before termination and rerun H02BFF. For example, to increase the maximum number of iterations to 500, include the statement
    CALL E04MHF/E04MHA(' Iteration Limit = 500 ')
    prior to calling H02BFF.
    Note that H02BUF uses an ‘infinite’ bound size of 1020 in the definition of l and u. In other words, any element of u greater than or equal to 1020 will be regarded as +∞ (and similarly any element of l less than or equal to -1020 will be regarded as -∞). If this value is deemed to be inappropriate, you are recommended to reset the value of the ‘infinite’ bound size and make any necessary changes to BL and/or BU prior to calling E04MFF/E04MFA. For example, to reset the value of the ‘infinite’ bound size to 10000, include the statement
    CALL E04MHF/E04MHA(' Infinite Bound Size = 1.0E+4 ')
    prior to calling E04MFF/E04MFA.
For an IP problem only:
  • If IFAIL=2, 3, 4, 7 or 9 on exit, you can obtain more information by making separate calls to H02BBF, H02BUF, H02BVF and H02BZF (in that order).
    Note that H02BUF uses an ‘infinite’ bound size of 1020 in the definition of l and u. In other words, any element of u greater than or equal to 1020 will be regarded as +∞ (and similarly any element of l less than or equal to -1020 will be regarded as -∞). If this value is deemed to be inappropriate, you are recommended to reset the value of the argument BIGBND (as described in H02BBF) and make any necessary changes to BL and/or BU prior to calling H02BBF.

10 Example

This example solves the same problem as the example for H02BUF, except that it treats it as an IP problem.
One of the applications of integer programming is to the so-called diet problem. Given the nutritional content of a selection of foods, the cost of each food, the amount available of each food and the consumer's minimum daily nutritional requirements, the problem is to find the cheapest combination. This gives rise to the following problem:
minimize
cT x
subject to
Ax≥b, 0≤x≤u,
where
  • c = 3 24 13 9 20 19 T , x = x 1,x 2,x 3,x 4,x 5,x 6 T ,
  • x 1 , x 2 and x 6 are real,
  • x 3 , x 4 and x 5 are integer,
  • A= 110 205 160 160 420 260 4 32 13 8 4 14 2 12 54 285 22 80 ,  b= 2000 55 800 and
  • u = 4 3 2 8 2 2 T .
The rows of A correspond to energy, protein and calcium and the columns of A correspond to oatmeal, chicken, eggs, milk, pie and bacon respectively.
The MPSX data representation of this problem is given in Section 10.2.

10.1 Program Text

Program Text (h02bffe.f90)

10.2 Program Data

Program Options (h02bffe.opt)

10.3 Program Results

Program Results (h02bffe.r)

H Chapter Contents
H Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


H02BUF : NAG Library, Mark 26

H Chapter Contents
H Chapter Introduction
NAG Library Manual

NAG Library Routine Document

H02BUF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

H02BUF reads data for a linear or integer programming problem from an external file which is in standard or compatible MPSX input format.

2 Specification

SUBROUTINE H02BUF ( INFILE, MAXN, MAXM, OPTIM, XBLDEF, XBUDEF, NMOBJ, NMRHS, NMRNG, NMBND, MPSLST, N, M, A, BL, BU, CVEC, X, INTVAR, CRNAME, NMPROB, IWORK, IFAIL)
INTEGER | INFILE, MAXN, MAXM, N, M, INTVAR(MAXN), IWORK(MAXN+MAXM), IFAIL
REAL (KIND=nag_wp) | XBLDEF, XBUDEF, A(MAXM,MAXN), BL(MAXN+MAXM), BU(MAXN+MAXM), CVEC(MAXN), X(MAXN)
LOGICAL | MPSLST
CHARACTER(3) | OPTIM
CHARACTER(8) | NMOBJ, NMRHS, NMRNG, NMBND, CRNAME(MAXN+MAXM), NMPROB

3 Description

H02BUF reads linear programming (LP) or integer programming (IP) problem data from an external file which is prepared in standard or compatible MPSX (see IBM (1971)) input format and then initializes n (the number of variables), m (the number of general linear constraints), the vectors c, l and u and the m by n matrix A for use with E04MFF/E04MFA or H02BBF, which are designed to solve problems of the form
minimize x∈Rn cT x  subject to  l≤ x Ax ≤u.
H02BUF may be followed by calls to either E04MFF/E04MFA (to solve an LP problem) or H02BBF and H02BZF (to solve an IP problem), possibly followed by a call to H02BVF (to print the solution using MPSX names).
Note that H02BUF uses an ‘infinite’ bound size of 1020 in the definition of l and u. In other words, any element of u greater than or equal to 1020 will be regarded as +∞ (and similarly any element of l less than or equal to -1020 will be regarded as -∞). If this value is deemed to be ‘inappropriate’, you are recommended to reset the value of either the optional parameter Infinite Bound Size (if an LP problem is being solved) or the argument BIGBND (if an IP problem is being solved) and make any necessary changes to BL and/or BU prior to calling E04MFF/E04MFA or H02BBF (as appropriate).
The documents for E04MFF/E04MFA, H02BVF and/or H02BBF and H02BZF should be consulted for further details.
MPSX input format
The input file of data may only contain two types of lines.
1. | Indicator lines (specifying the type of data which is to follow).
2. | Data lines (specifying the actual data).
The input file must not contain any blank lines. Any characters beyond column 80 are ignored. Indicator lines must not contain leading blank characters (in other words they must begin in column 1). The following displays the order in which the indicator lines must appear in the file:
NAME | user-given name
ROWS | data line(s)
COLUMNS | data line(s)
RHS | data line(s)
RANGES (optional) | data line(s)
BOUNDS (optional) | data line(s)
ENDATA |
The ‘user-given name’ specifies a name for the problem and must occupy columns 15–22. The name can either be blank or up to a maximum of 8 characters.
A data line follows the same fixed format made up of fields defined below. The contents of the fields may have different significance depending upon the section of data in which they appear.
 | Field 1 | Field 2 | Field 3 | Field 4 | Field 5 | Field 6
Columns | 2–3 | 5–12 | 15–22 | 25–36 | 40–47 | 50–61
Contents | Code | Name | Name | Value | Name | Value
The names and codes consist of ‘alphanumeric’ characters (i.e., a–z, A–Z, 0–9, +, -, asterisk (*), blank ( ), colon (:), dollar sign ($) or fullstop (.) only) and the names must not contain leading blank characters. Values are read using Fortran format E12.0. This allows values to be entered in several equivalent forms. For example, 1.2345678, 1.2345678 E+0, 123.45678E−2 and 12345678E−07 all represent the same number. It is safest to include an explicit decimal point.
Note that in order to ensure numeric values are interpreted as intended, they should be right-justified in the 12-character field, with no trailing blanks. This is because in some situations trailing blanks may be interpreted as zeros and this can dramatically affect the interpretation of the value. This is relevant if the value contains an exponent, or if it contains neither an exponent nor an explicit decimal point. For example, the fields
%%%%1.23E-2%
%%%%%%%123%%
may be interpreted as 1.23E−20 and 12300 respectively (where % is used to denote a blank). The actual behaviour is system-dependent.
Comment lines are allowed in the data file. These must have an asterisk (*) in column 1 and any characters in columns 2–80. In any data line, a dollar sign ($) as the first character in Field 3 or 5 indicates that the information from that point through column 80 consists of comments.
Columns outside the six fields must be blank, except for columns 72–80, whose contents are ignored by the routine. These columns may be used to enter a sequence number. A non-blank character outside the predefined six fields and columns 72–80 is considered to be a major error (IFAIL=11; see Section 6), unless it is part of a comment.
ROWS data line(s)
These lines specify row (constraint) names and their inequality types (i.e., =, ≥ or ≤).
Field 1: | defines the constraint type. It may be in column 2 or column 3.
N | free row, that is no constraint. It may be used to define the objective row.
G | greater than or equal to (i.e., ≥).
L | less than or equal to (i.e., ≤).
E | exactly equal to (i.e., =).
Field 2: | defines the row name.
Row type N stands for ‘Not binding’, also known as ‘Free’. It can be used to define the objective row. The objective row is a free row that specifies the vector c in the objective function. It is taken to be the first free row, unless some other free row name is specified by the argument NMOBJ (see Section 5). Note that the objective function must be included in the MPSX data file. Thus the maximum number of constraints (MAXM; see Section 5) in the problem must be m+1.
COLUMNS data line(s)
These lines specify the names to be assigned to the variables (columns) in the constraint matrix A, and define, in terms of column vectors, the actual values of the corresponding matrix elements.
Field 1: blank (ignored)
Field 2: gives the name of the column associated with the elements specified in the following fields.
Field 3: contains the name of a row.
Field 4: used in conjunction with Field 3 contains the value of the matrix element.
Field 5: is optional (may be used like Field 3).
Field 6: is optional (may be used like Field 4).
Note that only nonzero elements of A need to be specified in the COLUMNS section, as any unspecified elements are assumed to be zero.
RHS data line(s)
This section specifies the right-hand side values of the constraint matrix A. The lines specify the name of the RHS (right-hand side) vector given to the problem, the numerical values of the elements of the vector are also defined by the data lines and may appear in any order. The data lines have exactly the same format as the COLUMNS data lines, except that the column name is replaced by the RHS name. Note that any unspecified elements are assumed to be zero.
RANGES data line(s) (optional)
Ranges are used for constraints of the form l≤Ax≤u, where l and u are finite. The range of the constraint is r=u-l. Either l or u must be specified in the RHS section and r must be defined in this section.
The data lines have exactly the same format as the COLUMNS data lines, except that the column name is replaced by the RANGES name.
BOUNDS data line(s) (optional)
These lines specify limits on the values of the variables (l and u in l≤x≤u). If the variable is not specified in the bound set then it is automatically assumed to lie between default lower and upper bounds (usually 0 and +∞). Like an RHS column which is given a name, the set of variables in one bound set is also given a name.
Field 1: | specifies the type of bound or defines the variable type.
LO | lower bound
UP | upper bound
FX | fixed variable
FR | free variable (-∞ to +∞)
MI | lower bound is -∞
PL | upper bound is +∞. This is the default variable type.
Field 2: | identifies a name for the bound set.
Field 3: | identifies the column name of the variable belonging to this set.
Field 4: | identifies the value of the bound; this has a numerical value only in association with LO, UP, FX in Field 1, otherwise it is blank.
Field 5: | is blank and ignored.
Field 6: | is blank and ignored.
Note that if RANGES and BOUNDS sections are both present, the RANGES section must appear first.
Integer Problems
In IP problems there are two common integer variable types.
1. | 0–1 integer variables which represent ‘on’ or ‘off’ situations and
2. | General integer variables which are forced to take an integer value, in a specified range, at the optimal integer solution.
Integer variables can be defined in the following compatible and standard MPSX forms.
In the compatible MPSX format, the type of integer variables is defined in Field 1 of the BOUNDS section, that is:
Field 1: | specifies the type of the integer variable.
BV | 0–1 integer variable (bound value is 1.0).
UI | general integer variable (bound value is in Field 4).
In the standard MPSX format, the integer variables are treated the same as the ‘ordinary’ bounded variables, in the BOUNDS section. Integer markers are, however, introduced in the COLUMNS section to specify the integer variables. The indicator lines for these markers are:
 | Field 1 | Field 2 | Field 3 | Field 4 | Field 5 | Field 6
Columns | 2–3 | 5–12 | 15–22 | 25–36 | 40–47 | 50–61
Contents |  | INTEGER | ‘MARKER’ |  | ‘INTORG’ |
to mark the beginning of the integer variables and
 | Field 1 | Field 2 | Field 3 | Field 4 | Field 5 | Field 6
Columns | 2–3 | 5–12 | 15–22 | 25–36 | 40–47 | 50–61
Contents |  | INTEGER | ‘MARKER’ |  | ‘INTEND’ |
to mark the end. That is, any variables between these markers are treated as integer variables. Note that if the (INTEND) indicator line is not specified in the file then all the variables between the (INTORG) indicator line and the end of the COLUMNS section are assumed to be integer variables. The routine accepts both standard and/or compatible MPSX format as a means of specifying integer variables. This is illustrated in Section 10.2 in H02BFF.

4 References

IBM (1971) MPSX – Mathematical programming system Program Number 5734 XM4 IBM Trade Corporation, New York

5 Arguments

1:   INFILE – INTEGERInput
On entry: the unit number associated with the MPSX data file.
Constraint: 0≤INFILE≤99.
2:   MAXN – INTEGERInput
On entry: an upper limit for the number of variables in the problem.
Constraint: MAXN≥1.
3:   MAXM – INTEGERInput
On entry: an upper limit for the number of constraints (including the objective) in the problem.
Constraint: MAXM≥1.
4:   OPTIM – CHARACTER(3)Input
On entry: specifies the direction of the optimization. OPTIM must be set to 'MIN' for minimization and to 'MAX' for maximization.
Constraint: OPTIM='MIN' or 'MAX'.
5:   XBLDEF – REAL (KIND=nag_wp)Input
On entry: the default lower bound to be used for the variables in the problem when none is specified in the BOUNDS section of the MPSX data file. For a standard LP or IP problem XBLDEF would normally be set to zero.
6:   XBUDEF – REAL (KIND=nag_wp)Input
On entry: the default upper bound to be used for the variables in the problem when none is specified in the BOUNDS section of the MPSX data file. For a standard LP or IP problem XBUDEF would normally be set to ‘infinity’ (i.e., XBUDEF≥1020).
Constraint: XBUDEF≥XBLDEF.
7:   NMOBJ – CHARACTER(8)Input/Output
On entry: either the name of the objective function to be used for the optimization, or blank (in which case the first objective (free) row in the file is used).
On exit: the name of the objective row as defined in the MPSX data file.
8:   NMRHS – CHARACTER(8)Input/Output
On entry: either the name of the RHS set to be used for the optimization, or blank (in which case the first RHS set is used).
On exit: the name of the RHS set read in the MPSX data file.
9:   NMRNG – CHARACTER(8)Input/Output
On entry: either the name of the RANGE set to be used for the optimization, or blank (in which case the first RANGE set (if any) is used).
On exit: the name of the RANGE set read in the MPSX data file. This is blank if the MPSX data file does not have a RANGE set.
10:   NMBND – CHARACTER(8)Input/Output
On entry: either the name of the BOUNDS set to be used for the optimization, or blank (in which case the first BOUNDS set (if any) is used).
On exit: the name of the BOUNDS set read in the MPSX data file. This is blank if the MPSX data file does not have a BOUNDS set.
11:   MPSLST – LOGICALInput
On entry: if MPSLST=.TRUE., then a listing of the input data is sent to the current advisory message unit (as defined by X04ABF). This can be useful for debugging the MPSX data file.
12:   N – INTEGEROutput
On exit: n, the actual number of variables in the problem.
13:   M – INTEGEROutput
On exit: m, the actual number of general linear constraints in the problem.
14:   A MAXMMAXN – REAL (KIND=nag_wp) arrayOutput
On exit: A, the matrix of general linear constraints.
15:   BL MAXN+MAXM – REAL (KIND=nag_wp) arrayOutput
On exit: l, the lower bounds for all the variables and constraints in the following order. The first N elements of BL contain the bounds on the variables and the next M elements contain the bounds for the general linear constraints (if any). Note that an ‘infinite’ lower bound is indicated by BL j=-1.0E+20 and an equality constraint by BL j=BU j.
16:   BU MAXN+MAXM – REAL (KIND=nag_wp) arrayOutput
On exit: u, the upper bounds for all the variables and constraints in the following order. The first N elements of BU contain the bounds on the variables and the next M elements contain the bounds for the general linear constraints (if any). Note that an ‘infinite’ upper bound is indicated by BU j=1.0E+20 and an equality constraint by BU j=BL j.
17:   CVEC MAXN – REAL (KIND=nag_wp) arrayOutput
On exit: c, the coefficients of the objective function. The signs of these coefficients are determined by the problem (either LP or IP) and the direction of the optimization (see OPTIM above).
18:   X MAXN – REAL (KIND=nag_wp) arrayOutput
On exit: an initial estimate of the solution to the problem. More precisely, X j=1.0 if j is odd and 0.0 otherwise, for j=1,2,…,N.
19:   INTVAR MAXN – INTEGER arrayOutput
On exit: indicates which are the integer variables in the problem. More precisely, INTVAR k=1 if xk is an integer variable, and 0 otherwise, for k=1,2,…,N.
20:   CRNAME MAXN+MAXM – CHARACTER(8) arrayOutput
On exit: the MPSX names of all the variables and constraints in the problem in the following order. The first N elements contain the MPSX names for the variables and the next M elements contain the MPSX names for the general linear constraints (if any).
21:   NMPROB – CHARACTER(8)Output
On exit: the name of the problem as defined in the MPSX data file.
22:   IWORK MAXN+MAXM – INTEGER arrayWorkspace
23:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=3 to IFAIL=15 (apart from IFAIL=14) are caused by having either a corrupt or a nonstandard MPSX data file. Refer to Section 3 for a detailed description of the MPSX format which can be read by H02BUF. If MPSLST=.TRUE., the last line of printed output refers to the line in the MPSX data file which contains the reported error.
IFAIL=1
There are too many rows present in the data file. Increase MAXM by at least (M-MAXM) and rerun H02BUF.
IFAIL=2
There are too many columns present in the data file. Increase MAXN by at least (N-MAXN) and rerun H02BUF.
IFAIL=3
The objective function row was not found. There must be at least one row in the ROWS section with row type N for the objective row.
IFAIL=4
There are no rows specified in the ROWS section.
IFAIL=5
An illegal constraint type was detected in the ROWS section. The constraint type must be one of N, L, G or E.
IFAIL=6
An illegal row name was detected in the ROWS section. Names must be made up of alphanumeric characters with no leading blanks.
IFAIL=7
An illegal column name was detected in the COLUMNS section. Names must be made up of alphanumeric characters with no leading blanks.
IFAIL=8
An illegal bound type was detected in the BOUNDS section. The bound type must be one of LO, UP, FX, FR, MI, PL, BV or UI.
IFAIL=9
An unknown column name was detected in the BOUNDS section. All the column names must be specified in the COLUMNS section.
IFAIL=10
The last line in the file does not contain the ENDATA line indicator.
IFAIL=11
An illegal data line was detected in the file. This line is neither a comment line nor a valid data line.
IFAIL=12
An unknown row name was detected in COLUMNS or RHS or RANGES section. All the row names must be specified in the ROWS section.
IFAIL=13
There were no columns specified in the COLUMNS section.
IFAIL=14
An input argument is invalid.
IFAIL=15
Incorrect integer marker. In standard MPSX data format, integer variables should be defined between INTORG and INTEND markers.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

H02BUF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example solves the same problem as the example for H02BFF, except that it treats it as an LP problem.
One of the applications of linear programming is to the so-called diet problem. Given the nutritional content of a selection of foods, the cost of each food, the amount available of each food and the consumer's minimum daily nutritonal requirements, the problem is to find the cheapest combination. This gives rise to the following problem:
minimize
cT x
subject to
Ax≥b, 0≤x≤u,
where
c= 3 24 13 9 20 19 T,x=x 1,x 2,x 3,x 4,x 5,x 6 T is real,
A= 110 205 160 160 420 260 4 32 13 8 4 14 2 12 54 285 22 80 ,   b= 2000 55 800
and
u= 4 3 2 8 2 2 T .
The rows of A correspond to energy, protein and calcium and the columns of A correspond to oatmeal, chicken, eggs, milk, pie and bacon respectively.
The MPSX representation of the problem is given in Section 10.2.

10.1 Program Text

Program Text (h02bufe.f90)

10.2 Program Data

Program Options (h02bufe.opt)

10.3 Program Results

Program Results (h02bufe.r)

H Chapter Contents
H Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


H02BVF : NAG Library, Mark 26

H Chapter Contents
H Chapter Introduction
NAG Library Manual

NAG Library Routine Document

H02BVF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

H02BVF prints the solution to a linear or integer programming problem computed by E04MFF/E04MFA or H02BBF and H02BZF, with user-supplied names for the rows and columns.

2 Specification

SUBROUTINE H02BVF ( N, M, A, LDA, BL, BU, X, CLAMDA, ISTATE, CRNAME, IFAIL)
INTEGER | N, M, LDA, ISTATE(N+M), IFAIL
REAL (KIND=nag_wp) | A(LDA,*), BL(N+M), BU(N+M), X(N), CLAMDA(N+M)
CHARACTER(8) | CRNAME(N+M)

3 Description

H02BVF prints the solution to a linear or integer programming problem with user-supplied names for the rows and columns. All output is written to the current advisory message unit (as defined by X04ABF). The routine must be preceded in the same program by calls to H02BUF and either E04MFF/E04MFA (if an LP problem has been solved) or H02BBF and H02BZF (if an IP problem has been solved). The documents for E04MFF/E04MFA, H02BUF and/or H02BBF and H02BZF should be consulted for further details.

4 References

IBM (1971) MPSX – Mathematical programming system Program Number 5734 XM4 IBM Trade Corporation, New York

5 Arguments

1:   N – INTEGERInput
On entry: the number of variables, as returned by H02BUF.
Constraint: N>0.
2:   M – INTEGERInput
On entry: the number of general linear constraints, as returned by H02BUF.
Constraint: M≥0.
3:   A LDA* – REAL (KIND=nag_wp) arrayInput
Note: the second dimension of the array A must be at least N if M>0 and at least 1 if M=0.
On entry: the matrix of general linear constraints, as returned by H02BUF.
4:   LDA – INTEGERInput
On entry: this must be the same argument MAXM as supplied to H02BUF.
Constraint: LDA≥max 1,M.
5:   BL N+M – REAL (KIND=nag_wp) arrayInput
On entry: the lower bounds for all the constraints, as returned by E04MFF/E04MFA or H02BZF.
6:   BU N+M – REAL (KIND=nag_wp) arrayInput
On entry: the upper bounds for all the constraints, as returned by E04MFF/E04MFA or H02BZF.
7:   X N – REAL (KIND=nag_wp) arrayInput
On entry: the solution to the problem, as returned by E04MFF/E04MFA or H02BBF.
8:   CLAMDA N+M – REAL (KIND=nag_wp) arrayInput
On entry: the Lagrange-multipliers (reduced costs) for each constraint with respect to the working set, as returned by E04MFF/E04MFA or H02BZF.
9:   ISTATE N+M – INTEGER arrayInput
On entry: the status of every constraint in the working set at the solution, as returned by E04MFF/E04MFA or H02BZF.
10:   CRNAME N+M – CHARACTER(8) arrayInput
On entry: the user-defined names for all the variables and constraints, as returned by H02BUF.
11:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | N≤0,
or | M<0,
or | LDA<max 1,M.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

H02BVF is not thread safe and should not be called from a multithreaded user program. Please see Section 3.12.1 in How to Use the NAG Library and its Documentation for more information on thread safety.
H02BVF is not threaded in any implementation.

9 Further Comments

None.

10 Example

See Section 10 in H02BUF.
H Chapter Contents
H Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


H02BZF : NAG Library, Mark 26

H Chapter Contents
H Chapter Introduction
NAG Library Manual

NAG Library Routine Document

H02BZF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

H02BZF extracts more information associated with the solution of an integer programming problem computed by H02BBF.

2 Specification

SUBROUTINE H02BZF ( N, M, BL, BU, CLAMDA, ISTATE, IWORK, LIWORK, RWORK, LRWORK, IFAIL)
INTEGER | N, M, ISTATE(N+M), IWORK(LIWORK), LIWORK, LRWORK, IFAIL
REAL (KIND=nag_wp) | BL(N+M), BU(N+M), CLAMDA(N+M), RWORK(LRWORK)

3 Description

H02BZF extracts the following information associated with the solution of an integer programming problem computed by H02BBF. The upper and lower bounds used for the solution, the Lagrange-multipliers (costs), and the status of the variables at the solution.
In the branch and bound method employed by H02BBF, the arrays BL and BU are used to impose restrictions on the values of the integer variables in each sub-problem. That is, if the variable xj is restricted to take value vj in a particular sub-problem, then BL j=BU j=vj is set in the sub-problem. Thus, on exit from this routine, some of the elements of BL and BU which correspond to integer variables may contain these imposed values, rather than those originally supplied to H02BBF.

4 References

None.

5 Arguments

1:   N – INTEGERInput
On entry: this must be the same argument N as supplied to H02BBF.
Constraint: N>0.
2:   M – INTEGERInput
On entry: this must be the same argument M as supplied to H02BBF.
Constraint: M≥0.
3:   BL N+M – REAL (KIND=nag_wp) arrayOutput
On exit: if H02BBF exits with IFAIL=0, 7 or 9, the values in the array BL contain the lower bounds imposed on the integer solution for all the constraints. The first N elements contain the lower bounds on the variables, and the next M elements contain the lower bounds for the general linear constraints (if any).
4:   BU N+M – REAL (KIND=nag_wp) arrayOutput
On exit: if H02BBF exits with IFAIL=0, 7 or 9, the values in the array BU contain the upper bounds imposed on the integer solution for all the constraints. The first N elements contain the upper bounds on the variables, and the next M elements contain the upper bounds for the general linear constraints (if any).
5:   CLAMDA N+M – REAL (KIND=nag_wp) arrayOutput
On exit: if H02BBF exits with IFAIL=0, 7 or 9, the values in the array CLAMDA contain the values of the Lagrange-multipliers for each constraint with respect to the current working set. The first N elements contain the multipliers (reduced costs) for the bound constraints on the variables, and the next M elements contain the multipliers (shadow costs) for the general linear constraints (if any).
6:   ISTATE N+M – INTEGER arrayOutput
On exit: if H02BBF exits with IFAIL=0, 7 or 9, the values in the array ISTATE indicate the status of the constraints in the working set at an integer solution. Otherwise, ISTATE indicates the composition of the working set at the final iterate. The significance of each possible value of ISTATE j is as follows.
ISTATE j | Meaning
-2 | The constraint violates its lower bound by more than TOLFES (the feasibility tolerance, see H02BBF).
-1 | The constraint violates its upper bound by more than TOLFES.
-0 | The constraint is satisfied to within TOLFES, but is not in the working set.
-1 | This inequality constraint is included in the working set at its lower bound.
-2 | This inequality constraint is included in the working set at its upper bound.
-3 | This constraint is included in the working set as an equality. This value of ISTATE can occur only when BL j=BU j.
-4 | This corresponds to an integer solution being declared with xj being temporarily fixed at its current value. This value of ISTATE can occur only when IFAIL=0, 7 or 9 on exit from H02BBF.
7:   IWORK LIWORK – INTEGER arrayCommunication Array
On entry: this must be the same argument IWORK as supplied to H02BBF. It is used to pass information from H02BBF to H02BZF and therefore the contents of this array must not be changed before calling H02BZF.
8:   LIWORK – INTEGERInput
On entry: the dimension of the array IWORK as declared in the (sub)program from which H02BZF is called.
9:   RWORK LRWORK – REAL (KIND=nag_wp) arrayCommunication Array
On entry: this must be the same argument RWORK as supplied to H02BBF. It is used to pass information from H02BBF to H02BZF and therefore the contents of this array must not be changed before calling H02BZF.
10:   LRWORK – INTEGERInput
On entry: the dimension of the array RWORK as declared in the (sub)program from which H02BZF is called.
11:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | N≤0,
or | M<0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

H02BZF is not threaded in any implementation.

9 Further Comments

None.

10 Example

One of the applications of integer programming is to the so-called diet problem. Given the nutritional content of a selection of foods, the cost of each food, the amount available of each food and the consumer's minimum daily nutritional requirements, the problem is to find the cheapest combination. This gives rise to the following problem:
minimize
cT x
subject to
Ax≥b, 0≤x≤u,
where
c= 3 24 13 9 20 19 T,x=x 1,x 2,x 3,x 4,x 5,x 6 T
is integer,
A= 110 205 160 160 420 260 4 32 13 8 4 14 2 12 54 285 22 80 ,   b= 2000 55 800
and
u= 4 3 2 8 2 2 T
The rows of A correspond to energy, protein and calcium and the columns of A correspond to oatmeal, chicken, eggs, milk, pie and bacon respectively.
The following program solves the above problem to obtain the optimal integer solution and then examines the effect of increasing the energy required to 2200 units.

10.1 Program Text

Program Text (h02bzfe.f90)

10.2 Program Data

Program Data (h02bzfe.d)

10.3 Program Results

Program Results (h02bzfe.r)

H Chapter Contents
H Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


H02CBF : NAG Library, Mark 26

H Chapter Contents
H Chapter Introduction
NAG Library Manual

NAG Library Routine Document

H02CBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.
Note: this routine uses optional parameters to define choices in the problem specification and in the details of the algorithm. If you wish to use default settings for all of the optional parameters, you need only read Sections 1 to 10 of this document. If, however, you wish to reset some or all of the settings please refer to Section 11 for a detailed description of the algorithm, to Section 12 for a detailed description of the specification of the optional parameters and to Section 13 for a detailed description of the monitoring information produced by the routine.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
▸▿ 9 Further Comments
9.1 Scaling
9.2 Description of the Printed Output
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results
▸▿ 11 Algorithmic Details
11.1 Overview
11.2 Definition of the Search Direction
11.3 The Main Iteration
11.4 Choosing the Initial Working Set
▸▿ 12 Optional Parameters
12.1 Description of the Optional Parameters
13 Description of Monitoring Information

1 Purpose

H02CBF solves general quadratic programming problems with integer constraints on the variables. It is not intended for large sparse problems.

2 Specification

SUBROUTINE H02CBF ( N, NCLIN, A, LDA, BL, BU, CVEC, H, LDH, QPHESS, INTVAR, LINTVR, MDEPTH, ISTATE, XS, OBJ, AX, CLAMDA, STRTGY, IWRK, LIWRK, WRK, LWRK, MONIT, IFAIL)
INTEGER | N, NCLIN, LDA, LDH, INTVAR(LINTVR), LINTVR, MDEPTH, ISTATE(N+NCLIN), STRTGY, IWRK(LIWRK), LIWRK, LWRK, IFAIL
REAL (KIND=nag_wp) | A(LDA,*), BL(N+NCLIN), BU(N+NCLIN), CVEC(*), H(LDH,*), XS(N), OBJ, AX(max(1,NCLIN)), CLAMDA(N+NCLIN), WRK(LWRK)
EXTERNAL | QPHESS, MONIT

3 Description

H02CBF uses a ‘Branch and Bound’ algorithm in conjunction with E04NFF to try and determine integer solutions to a general quadratic programming problem. The problem is assumed to be stated in the following general form:
minimize x∈Rn f x  subject to  l≤ x Ax ≤u,
where A is an mL by n matrix and f x may be specified in a variety of ways depending upon the particular problem to be solved. The available forms for f x are listed in Table 1, in which the prefixes FP, LP and QP stand for ‘feasible point’, ‘linear programming’ and ‘quadratic programming’ respectively and c is an n-element vector.
Problem type | f x | Matrix H
FP | Not applicable | Not applicable
LP | cT x | Not applicable
QP1 | cT x+12 xT Hx | symmetric
QP2 | cT x+12 xT Hx | symmetric
QP3 | cT x+12 xTHT Hx | m by n upper trapezoidal
QP4 | cT x+12 xTHT Hx | m by n upper trapezoidal
Table 1
Only when the problem is linear or the matrix H is positive definite can the technique be guaranteed to work; but often useful results can be obtained for a wider class of problems.
The default problem type is QP2 and other objective functions are selected by using the optional parameter Problem Type. For problems of type FP, the objective function is omitted and H02CBF attempts to find a feasible point for the set of constraints.
Branch and bound consists firstly of obtaining a solution without any of the variables x=x 1,x 2,…,xn T constrained to be integer. Suppose x 1 ought to be integer, but at the optimal value just computed x 1=2.4. A constraint x 1≤2 is added to the system and the second problem solved. A constraint x 1≥3 gives rise to a third sub-problem. In a similar manner a whole series of sub-problems may be generated, corresponding to integer constraints on the variables. The sub-problems are all solved using E04NFF.
In practice the routine tries to compute an integer solution as quickly as possible using a depth-first approach, since this helps determine a realistic cut-off value. If we have a cut-off value, say the value of the function at this first integer solution, and any sub-problem, W say, has a solution value greater than this cut-off value, then subsequent sub-problems of W must have solutions greater than the value of the solution at W and therefore need not be computed. Thus a knowledge of a good cut-off value can result in fewer sub-problems being solved and thus speed up the operation of the routine. (See the description of MONIT in Section 5 for details of how you can supply your own cut-off value.)

4 References

Gill P E, Hammarling S, Murray W, Saunders M A and Wright M H (1986) Users' guide for LSSOL (Version 1.0) Report SOL 86-1 Department of Operations Research, Stanford University
Gill P E and Murray W (1978) Numerically stable methods for quadratic programming Math. Programming 14 349–372
Gill P E, Murray W, Saunders M A and Wright M H (1984) Procedures for optimization problems with a mixture of bounds and general linear constraints ACM Trans. Math. Software 10 282–298
Gill P E, Murray W, Saunders M A and Wright M H (1989) A practical anti-cycling procedure for linearly constrained optimization Math. Programming 45 437–474
Gill P E, Murray W, Saunders M A and Wright M H (1991) Inertia-controlling methods for general quadratic programming SIAM Rev. 33 1–36
Gill P E, Murray W and Wright M H (1981) Practical Optimization Academic Press
Pardalos P M and Schnitger G (1988) Checking local optimality in constrained quadratic programming is NP-hard Operations Research Letters 7 33–35

5 Arguments

1:   N – INTEGERInput
On entry: n, the number of variables.
Constraint: N>0.
2:   NCLIN – INTEGERInput
On entry: mL, the number of general linear constraints.
Constraint: NCLIN≥0.
3:   A LDA* – REAL (KIND=nag_wp) arrayInput
Note: the second dimension of the array A must be at least N if NCLIN>0 and at least 1 if NCLIN=0.
On entry: the ith row of A must contain the coefficients of the ith general linear constraint, for i=1,2,…,mL.
If NCLIN=0, the array A is not referenced.
4:   LDA – INTEGERInput
On entry: the first dimension of the array A as declared in the (sub)program from which H02CBF is called.
Constraint: LDA≥max 1,NCLIN.
5:   BL N+NCLIN – REAL (KIND=nag_wp) arrayInput
6:   BU N+NCLIN – REAL (KIND=nag_wp) arrayInput
On entry: BL must contain the lower bounds and BU the upper bounds, for all the constraints in the following order. The first n elements of each array must contain the bounds on the variables, and the next mL elements the bounds for the general linear constraints (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set BL j≤-bigbnd, and to specify a nonexistent upper bound (i.e., uj=+∞), set BU j≥bigbnd; the default value of bigbnd is 1020, but this may be changed by the Infinite Bound Size. To specify the jth constraint as an equality, set BL j=BU j=β, say, where β<bigbnd.
Constraints:
  • BL j≤BU j, for j=1,2,…,N+NCLIN;
  • if BL j=BU j=β, β<bigbnd.
7:   CVEC* – REAL (KIND=nag_wp) arrayInput
Note: the dimension of the array CVEC must be at least N if the problem is of type LP, QP2 (the default) or QP4, and at least 1 otherwise.
On entry: the coefficients of the explicit linear term of the objective function when the problem is of type LP, QP2 (the default) and QP4.
If the problem is of type FP, QP1, or QP3, CVEC is not referenced.
8:   H LDH* – REAL (KIND=nag_wp) arrayInput
Note: the second dimension of the array H must be at least N if it is to be used to store H explicitly, and at least 1 otherwise.
On entry: may be used to store the quadratic term H of the QP objective function if desired. In some cases, you need not use H to store H explicitly (see the specification of QPHESS). The elements of H are referenced only by QPHESS. The number of rows of H is denoted by m, whose default value is n. (The Hessian Rows may be used to specify a value of m<n.)
If the default version of QPHESS is used and the problem is of type QP1 or QP2 (the default), the first m rows and columns of H must contain the leading m by m rows and columns of the symmetric Hessian matrix H. Only the diagonal and upper triangular elements of the leading m rows and columns of H are referenced. The remaining elements need not be assigned.
If the default version of QPHESS is used and the problem is of type QP3 or QP4, the first m rows of H must contain an m by n upper trapezoidal factor of the symmetric Hessian matrix HT H. The factor need not be of full rank, i.e., some of the diagonal elements may be zero. However, as a general rule, the larger the dimension of the leading nonsingular sub-matrix of H, the fewer iterations will be required. Elements outside the upper trapezoidal part of the first m rows of H need not be assigned.
In other situations, it may be desirable to compute Hx or HT Hx without accessing H – for example, if H or HT H is sparse or has special structure. The arguments H and LDH may then refer to any convenient array.
If the problem is of type FP or LP, H is not referenced.
9:   LDH – INTEGERInput
On entry: the first dimension of the array H as declared in the (sub)program from which H02CBF is called.
Constraints:
  • if the problem is of type QP1, QP2 (the default), QP3 or QP4, LDH≥N or at least the value of the optional parameter Hessian Rows (default value=n);
  • if the problem is of type FP or LP, LDH≥1.
10:   QPHESS – SUBROUTINE, supplied by the NAG Library or the user.External Procedure
In general, you need not provide a version of QPHESS, because a ‘default’ subroutine with name E04NFU is included in the Library. However, the algorithm of H02CBF requires only the product of H or HT H and a vector x; and in some cases you may obtain increased efficiency by providing a version of QPHESS that avoids the need to define the elements of the matrices H or HT H explicitly. QPHESS is not referenced if the problem is of type FP or LP, in which case QPHESS may be the routine E04NFU.
The specification of QPHESS is:
SUBROUTINE QPHESS ( N, JTHCOL, H, LDH, X, HX)
INTEGER | N, JTHCOL, LDH
REAL (KIND=nag_wp) | H(LDH,*), X(N), HX(N)
1:   N – INTEGERInput
On entry: this is the same argument N as supplied to H02CBF.
2:   JTHCOL – INTEGERInput
On entry: specifies whether or not the vector x is a column of the identity matrix.
JTHCOL=j>0
The vector x is the jth column of the identity matrix, and hence Hx or HT Hx is the jth column of H or HT H, respectively, which may in some cases require very little computation and QPHESS may be coded to take advantage of this. However special code is not necessary because x is always stored explicitly in the array X.
JTHCOL=0
x has no special form.
3:   H LDH* – REAL (KIND=nag_wp) arrayInput
On entry: this is the same argument H as supplied to H02CBF.
4:   LDH – INTEGERInput
On entry: this is the same argument LDH as supplied to H02CBF.
5:   X N – REAL (KIND=nag_wp) arrayInput
On entry: the vector x.
6:   HX N – REAL (KIND=nag_wp) arrayOutput
On exit: the product Hx if the problem is of type QP1 or QP2 (the default), or the product HT Hx if the problem is of type QP3 or QP4.
QPHESS must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which H02CBF is called. Arguments denoted as Input must not be changed by this procedure.
11:   INTVAR LINTVR – INTEGER arrayInput
On entry: INTVAR i must contain the index of the solution vector x which is required to be integer. For example, if x 1 and x 3 are constrained to take integer values then INTVAR 1 might be set to 1 and INTVAR 2 to 3. The order in which the indices are specified is important, since this determines the order in which the sub-problems are generated. As a rule-of-thumb, the important variables should always be specified first. Thus, in the above example, if x 3 relates to a more important quantity than x 1, then it might be advantageous to set INTVAR 1=3 and INTVAR 2=1. If k is the smallest integer such that INTVAR k is less than or equal to zero then H02CBF assumes that k-1 variables are constrained to be integer; components INTVAR k+1, …, INTVAR LINTVR are not referenced.
12:   LINTVR – INTEGERInput
On entry: the dimension of the array INTVAR as declared in the (sub)program from which H02CBF is called. Often LINTVR is the number of variables that are constrained to be integer.
Constraint: LINTVR>0.
13:   MDEPTH – INTEGERInput
On entry: the maximum depth (i.e., number of extra constraints) that H02CBF may insert before admitting failure.
Suggested value: MDEPTH=3×N/2.
Constraint: MDEPTH≥1.
14:   ISTATE N+NCLIN – INTEGER arrayInput/Output
On entry: need not be set if the (default) optional parameter Cold Start is used.
If the optional parameter Warm Start has been chosen, ISTATE specifies the desired status of the constraints at the start of the feasibility phase. More precisely, the first n elements of ISTATE refer to the upper and lower bounds on the variables, and the next mL elements refer to the general linear constraints (if any). Possible values for ISTATE j are as follows:
ISTATE j | Meaning
0 | The corresponding constraint should not be in the initial working set.
1 | The constraint should be in the initial working set at its lower bound.
2 | The constraint should be in the initial working set at its upper bound.
3 | The constraint should be in the initial working set as an equality. This value must not be specified unless BL j=BU j.
The values -2, -1 and 4 are also acceptable but will be reset to zero by the routine. If H02CBF has been called previously with the same values of N and NCLIN, ISTATE already contains satisfactory information. (See also the description of the optional parameter Warm Start.) The routine also adjusts (if necessary) the values supplied in XS to be consistent with ISTATE.
Constraint: -2≤ISTATE j≤4, for j=1,2,…,N+NCLIN.
On exit: the status of the constraints in the working set at the point returned in XS. The significance of each possible value of ISTATE j is as follows:
ISTATE j | Meaning
-2 | The constraint violates its lower bound by more than the feasibility tolerance.
-1 | The constraint violates its upper bound by more than the feasibility tolerance.
-0 | The constraint is satisfied to within the feasibility tolerance, but is not in the working set.
-1 | This inequality constraint is included in the working set at its lower bound.
-2 | This inequality constraint is included in the working set at its upper bound.
-3 | This constraint is included in the working set as an equality. This value of ISTATE can occur only when BL j=BU j.
-4 | This corresponds to optimality being declared with XS j being temporarily fixed at its current value. This value of ISTATE can occur only when IFAIL=1 on exit.
15:   XS N – REAL (KIND=nag_wp) arrayInput/Output
On entry: an initial estimate of the solution.
On exit: the point at which H02CBF terminated. If IFAIL=0, 1 or 3, XS contains an estimate of the solution.
16:   OBJ – REAL (KIND=nag_wp)Output
On exit: the value of the objective function at x if x is feasible, or the sum of infeasibilities at x otherwise. If the problem is of type FP and x is feasible, OBJ is set to zero.
17:   AX max 1,NCLIN – REAL (KIND=nag_wp) arrayOutput
On exit: the final values of the linear constraints Ax.
If NCLIN=0, AX is not referenced.
18:   CLAMDA N+NCLIN – REAL (KIND=nag_wp) arrayOutput
On exit: the values of the Lagrange-multipliers for each constraint with respect to the current working set. The first n elements contain the multipliers for the bound constraints on the variables, and the next mL elements contain the multipliers for the general linear constraints (if any). If ISTATE j=0 (i.e., constraint j is not in the working set), CLAMDA j is zero. If x is optimal, CLAMDA j should be non-negative if ISTATE j=1, non-positive if ISTATE j=2 and zero if ISTATE j=4.
19:   STRTGY – INTEGERInput
On entry: determines a branching strategy to be used throughout the computation, as follows:
STRTGY | Meaning
0 | Always left branch first, i.e., impose an upper bound constraint on the variable first.
1 | Always right branch first, i.e., impose a lower bound constraint on the variable first.
2 | Branch towards the nearest integer, i.e., if xk=2.4 then impose an upper bound constraint xk≤2, whereas if xk=2.6 then impose the lower bound constraint xk≥3.0.
3 | A random choice is made between a left-hand and a right-hand branch.
Constraint: STRTGY=0, 1, 2 or 3.
20:   IWRK LIWRK – INTEGER arrayWorkspace
21:   LIWRK – INTEGERInput
On entry: the dimension of the array IWRK as declared in the (sub)program from which H02CBF is called.
Constraint: LIWRK≥2×N+3+2×MDEPTH.
22:   WRK LWRK – REAL (KIND=nag_wp) arrayWorkspace
23:   LWRK – INTEGERInput
On entry: the dimension of the array WRK as declared in the (sub)program from which H02CBF is called.
Constraints:
  • if the problem type is QP2 (the default) or QP4,
    • if NCLIN>0, LWRK≥2×N 2+9×N+5×NCLIN+4×MDEPTH;
    • if NCLIN=0, LWRK≥N 2+9×N+4×MDEPTH;
  • if the problem type is QP1 or QP3,
    • if NCLIN>0, LWRK≥2×N 2+8×N+5×NCLIN+4×MDEPTH;
    • if NCLIN=0, LWRK≥N 2+8×N+4×MDEPTH;
  • if the problem type is LP,
    • if NCLIN=0, LWRK≥9×N+1+4×MDEPTH;
    • if NCLIN≥N, LWRK≥2×N 2+9×N+5×NCLIN+4×MDEPTH;
    • otherwise LWRK≥2× NCLIN+1 2+9×N+5×NCLIN+4×MDEPTH;
  • if the problem type is FP,
    • if NCLIN=0, LWRK≥8×N+1+4×MDEPTH;
    • if NCLIN≥N, LWRK≥2×N 2+8×N+5×NCLIN+4×MDEPTH;
    • otherwise LWRK≥2× NCLIN+1 2+8×N+5×NCLIN+4×MDEPTH.
24:   MONIT – SUBROUTINE, supplied by the NAG Library or the user.External Procedure
MONIT may be used to print out intermediate output and to affect the course of the computation. Specifically, it allows you to specify a realistic value for the cut-off value (see Section 3) and to terminate the algorithm. If you do not require any intermediate output, have no estimate of the cut-off value and require an exhaustive tree search then MONIT may be the dummy routine H02CBU.
The specification of MONIT is:
SUBROUTINE MONIT ( INTFND, NODES, DEPTH, OBJ, X, BSTVAL, BSTSOL, BL, BU, N, HALT, COUNT)
INTEGER | INTFND, NODES, DEPTH, N, COUNT
REAL (KIND=nag_wp) | OBJ, X(N), BSTVAL, BSTSOL(N), BL(N), BU(N)
LOGICAL | HALT
1:   INTFND – INTEGERInput
On entry: specifies the number of integer solutions obtained so far.
2:   NODES – INTEGERInput
On entry: specifies the number of nodes (sub-problems) solved so far.
3:   DEPTH – INTEGERInput
On entry: specifies the depth in the tree of sub-problems the algorithm has now reached.
4:   OBJ – REAL (KIND=nag_wp)Input
On entry: specifies the value of the objective function of the end of the latest sub-problem.
5:   X N – REAL (KIND=nag_wp) arrayInput
On entry: specifies the values of the independent variables at the end of the latest sub-problem.
6:   BSTVAL – REAL (KIND=nag_wp)Input/Output
On entry: normally specifies the value of the best integer solution found so far.
On exit: may be set a cut-off value if you are an experienced user as follows. Before an integer solution has been found BSTVAL will be set by H02CBF to the largest machine representable number (see X02ALF). If you know that the solution being sought is a much smaller number, then BSTVAL may be set to this number as a cut-off value (see Section 3). Beware of setting BSTVAL too small, since then no integer solutions will be discovered. Also make sure that BSTVAL is set using a statement of the form
IF (INTFND.EQ.0) BSTVAL= cut-off value
on entry to MONIT. This statement will not prevent the normal operation of the algorithm when subsequent integer solutions are found. It would be a grievous mistake to unconditionally set BSTVAL and if you have any doubts whatsoever about the correct use of this argument then you are strongly recommended to leave it unchanged.
7:   BSTSOL N – REAL (KIND=nag_wp) arrayInput
On entry: specifies the solution vector which gives rise to the best integer solution value so far discovered.
8:   BL N – REAL (KIND=nag_wp) arrayInput
On entry: BL i specifies the current lower bounds on the variable xi.
9:   BU N – REAL (KIND=nag_wp) arrayInput
On entry: BU i specifies the current upper bounds on the variable xi.
10:   N – INTEGERInput
On entry: specifies the number of variables.
11:   HALT – LOGICALInput/Output
On entry: will have the value .FALSE..
On exit: if HALT is set to .TRUE., E04NFF/E04NFA will be brought to a halt with IFAIL=-1. This facility may be useful if you are content with any integer solution, or with any integer solution that fits certain criteria. Under these circumstances setting HALT=.TRUE. can save considerable unnecessary computation.
12:   COUNT – INTEGERInput/Output
On entry: unchanged from previous call.
On exit: may be used by you to save the last value of INTFND. If a subsequent call of MONIT has a value of INTFND which is greater than COUNT, then you know that a new integer solution has been found at this node.
MONIT must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which H02CBF is called. Arguments denoted as Input must not be changed by this procedure.
25:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=-1
Algorithm terminated at your request (HALT=.TRUE.).
IFAIL=1
Input argument error immediately detected.
IFAIL=2
No integer solution found. (Check that BSTVAL has not been set too small.)
IFAIL=3
MDEPTH is too small. Increase the value of MDEPTH and re-enter H02CBF.
IFAIL=4
The basic problem (without integer constraints) is unbounded.
IFAIL=5
The basic problem is infeasible.
IFAIL=6
The basic problem requires too many iterations.
IFAIL=7
The basic problem has a reduced Hessian which exceeds its assigned dimension.
IFAIL=8
The basic problem has an invalid argument setting.
IFAIL=9
The basic problem, as defined, is not standard.
IFAIL=10
LIWRK is too small.
IFAIL=11
LWRK is too small.
IFAIL=12
An internal error has occurred within the routine. Please contact NAG with details of the call to H02CBF.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

H02CBF implements a numerically stable active set strategy and returns solutions that are as accurate as the condition of the problem warrants on the machine.

8 Parallelism and Performance

H02CBF is not thread safe and should not be called from a multithreaded user program. Please see Section 3.12.1 in How to Use the NAG Library and its Documentation for more information on thread safety.
H02CBF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
H02CBF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

This section contains some comments on scaling and a description of the printed output.

9.1 Scaling

Sensible scaling of the problem is likely to reduce the number of iterations required and make the problem less sensitive to perturbations in the data, thus improving the condition of the problem. In the absence of better information it is usually sensible to make the Euclidean lengths of each constraint of comparable magnitude. See Chapter E04 and Gill et al. (1981) for further information and advice.

9.2 Description of the Printed Output

This section describes the (default) intermediate printout and final printout produced by H02CBF. The intermediate printout is a subset of the monitoring information produced by the routine at every iteration (see Section 13). You can control the level of printed output (see the description of the Print Level in Section 12.1). Note that the intermediate printout and final printout are produced only if Print Level≥10 (the default).
The following line of summary output (<80 characters) is produced at every iteration. In all cases, the values of the quantities printed are those in effect on completion of the given iteration.
Itn | is the iteration count.
Step | is the step taken along the computed search direction. If a constraint is added during the current iteration, Step will be the step to the nearest constraint. When the problem is of type LP, the step can be greater than one during the optimality phase.
Ninf | is the number of violated constraints (infeasibilities). This will be zero during the optimality phase.
Sinf/Objective | is the value of the current objective function. If x is not feasible, Sinf gives a weighted sum of the magnitudes of constraint violations. If x is feasible, Objective is the value of the objective function. The output line for the final iteration of the feasibility phase (i.e., the first iteration for which Ninf is zero) will give the value of the true objective at the first feasible point. During the optimality phase, the value of the objective function will be nonincreasing. During the feasibility phase, the number of constraint infeasibilities will not increase until either a feasible point is found, or the optimality of the multipliers implies that no feasible point exists. Once optimal multipliers are obtained, the number of infeasibilities can increase, but the sum of infeasibilities will either remain constant or be reduced until the minimum sum of infeasibilities is found.
Norm Gz | is ZRT gFR , the Euclidean norm of the reduced gradient with respect to ZR (see Sections 11.2 and 11.4). During the optimality phase, this norm will be approximately zero after a unit step.
The final printout includes a listing of the status of every variable and constraint.
The following describes the printout for each variable. A full stop (.) is printed for any numerical value that is zero.
A key is sometimes printed before State to give some additional information about the state of a variable.
Varbl | gives the name (V) and index j, for j=1,2,…,n, of the variable.
State gives the state of the variable (FR if neither bound is in the working set, EQ if a fixed variable, LL if on its lower bound, UL if on its upper bound, TF if temporarily fixed at its current value). If Value lies outside the upper or lower bounds by more than the Feasibility Tolerance (default value=ε, where ε is the machine precision; see Section 12.1), State will be ++ or -- respectively.
A | Alternative optimum possible. The variable is active at one of its bounds, but its Lagrange-multiplier is essentially zero. This means that if the variable were allowed to start moving away from its bound, there would be no change to the objective function. The values of the other free variables might change, giving a genuine alternative solution. However, if there are any degenerate variables (labelled D), the actual change might prove to be zero, since one of them could encounter a bound immediately. In either case the values of the Lagrange-multipliers might also change.
D | Degenerate. The variable is free, but it is equal to (or very close to) one of its bounds.
I | Infeasible. The variable is currently violating one of its bounds by more than the Feasibility Tolerance.
Value | is the value of the variable at the final iterate.
Lower Bound | is the lower bound specified for the variable. None indicates that BL j≤-bigbnd.
Upper Bound | is the upper bound specified for the variable. None indicates that BU j≥bigbnd.
Slack | is the difference between the variable Value and the nearer of its (finite) bounds BL j and BU j. A blank entry indicates that the associated variable is not bounded (i.e., BL j≤-bigbnd and BU j≥bigbnd).
The meaning of the printout for general constraints is the same as that given above for variables, with ‘variable’ replaced by ‘constraint’, BL j and BU j are replaced by BL n+j and BU n+j respectively, and with the following change in the heading.
L Con gives the name (L) and index j, for j=1,2,…,m, of the constraint.
Note that movement off a constraint (as opposed to a variable moving away from its bound) can be interpreted as allowing the entry in the Slack column to become positive.
Numerical values are output with a fixed number of digits; they are not guaranteed to be accurate to this precision.

10 Example

This example minimizes the quadratic function f x=cT x+12 xT Hx, where
c = -0.02,-0.2,-0.2,-0.2,-0.2,0.04,0.04 T
H= 2 0 0 0 0 0 0 0 2 0 0 0 0 0 0 0 2 2 0 0 0 0 0 2 2 0 0 0 0 0 0 0 2 0 0 0 0 0 0 0 -2 -2 0 0 0 0 0 -2 -2
subject to the bounds
-0.01≤x 1≤0.01 -0.1 0≤x 2≤0.15 -0.01≤x 3≤0.03 -0.04≤x 4≤0.02 -0.1 0≤x 5≤0.05 -0.01≤x 6 -0.01≤x 7
to the general constraints
x 1 + x 2 + x 3 + x 4 + x 5 + x 6 + x 7 = -0.13 0.15 x 1 + 0.04 x 2 + 0.02 x 3 + 0.04 x 4 + 0.02 x 5 + 0.01 x 6 + 0.03 x 7 ≤ -0.0049 0.03 x 1 + 0.05 x 2 + 0.08 x 3 + 0.02 x 4 + 0.06 x 5 + 0.01 x 6 ≤ -0.0064 0.02 x 1 + 0.04 x 2 + 0.01 x 3 + 0.02 x 4 + 0.02 x 5 ≤ -0.0037 0.02 x 1 + 0.03 x 2 + 0.01 x 5 ≤ -0.0012 -0.0992 ≤ 0.70 x 1 + 0.75 x 2 + 0.80 x 3 + 0.75 x 4 + 0.80 x 5 + 0.97 x 6 -0.003 ≤ 0.02 x 1 + 0.06 x 2 + 0.08 x 3 + 0.12 x 4 + 0.02 x 5 + 0.01 x 6 + 0.97 x 7 ≤ -0.002
and the variable x 4 is constrained to be integer.
The initial point, which is infeasible, is
x 0 = -0.01,-0.03,0.0,-0.01,-0.1,0.02,0.01 T .
The optimal solution (to five figures) is
x* = -0.01,-0.073328,-0.00025809,0.0,-0.063354,0.014109,0.0028312 T .
The document for H02CCF includes an example program to solve the same problem using some of the optional parameters described in Section 12.

10.1 Program Text

Program Text (h02cbfe.f90)

10.2 Program Data

Program Data (h02cbfe.d)

10.3 Program Results

Program Results (h02cbfe.r)

Note: the remainder of this document is intended for more advanced users. Section 11 contains a detailed description of the algorithm which may be needed in order to understand Sections 12 and 13. Section 12 describes the optional parameters which may be set by calls to H02CCF and/or H02CDF. Section 13 describes the quantities which can be requested to monitor the course of the computation.

11 Algorithmic Details

H02CBF implements a basic branch and bound algorithm (see Section 3) using E04NFF as its basic sub-problem solver. See below for details of its algorithm.

11.1 Overview

H02CBF is based on an inertia-controlling method that maintains a Cholesky factorization of the reduced Hessian (see below). The method is based on that of Gill and Murray (1978), and is described in detail by Gill et al. (1991). Here we briefly summarise the main features of the method. Where possible, explicit reference is made to the names of variables that are arguments of H02CBF or appear in the printed output. H02CBF has two phases:
(i) | finding an initial feasible point by minimizing the sum of infeasibilities (the feasibility phase), and
(ii) | minimizing the quadratic objective function within the feasible region (the optimality phase).
The computations in both phases are performed by the same subroutines. The two-phase nature of the algorithm is reflected by changing the function being minimized from the sum of infeasibilities to the quadratic objective function. The feasibility phase does not perform the standard simplex method (i.e., it does not necessarily find a vertex), except in the LP case when mL≤n. Once any iterate is feasible, all subsequent iterates remain feasible.
H02CBF has been designed to be efficient when used to solve a sequence of related problems – for example, within a sequential quadratic programming method for nonlinearly constrained optimization (e.g., E04WDF). In particular, you may specify an initial working set (the indices of the constraints believed to be satisfied exactly at the solution); see the discussion of the Warm Start in Section 12.1.
In general, an iterative process is required to solve a quadratic program. (For simplicity, we shall always consider a typical iteration and avoid reference to the index of the iteration.) Each new iterate x- is defined by
x-=x+αp (1)
where the step length α is a non-negative scalar, and p is called the search direction.
At each point x, a working set of constraints is defined to be a linearly independent subset of the constraints that are satisfied ‘exactly’ (to within the tolerance defined by the Feasibility Tolerance; see Section 12.1). The working set is the current prediction of the constraints that hold with equality at the solution of a linearly constrained QP problem. The search direction is constructed so that the constraints in the working set remain unaltered for any value of the step length. For a bound constraint in the working set, this property is achieved by setting the corresponding element of the search direction to zero. Thus, the associated variable is fixed, and specification of the working set induces a partition of x into fixed and free variables. During a given iteration, the fixed variables are effectively removed from the problem; since the relevant elements of the search direction are zero, the columns of A corresponding to fixed variables may be ignored.
Let mW denote the number of general constraints in the working set and let nFX denote the number of variables fixed at one of their bounds (mW and nFX are the quantities Lin and Bnd in the monitoring file output from H02CBF; see Section 13). Similarly, let nFR (nFR=n-nFX) denote the number of free variables. At every iteration, the variables are reordered so that the last nFX variables are fixed, with all other relevant vectors and matrices ordered accordingly.

11.2 Definition of the Search Direction

Let AFR denote the mW by nFR sub-matrix of general constraints in the working set corresponding to the free variables, and let pFR denote the search direction with respect to the free variables only. The general constraints in the working set will be unaltered by any move along p if
AFRpFR=0. (2)
In order to compute pFR, the TQ factorization of AFR is used:
AFRQFR=0 T, (3)
where T is a nonsingular mW by mW upper triangular matrix (i.e., t ij=0 if i>j), and the nonsingular nFR by nFR matrix QFR is the product of orthogonal transformations (see Gill et al. (1984)). If the columns of QFR are partitioned so that
QFR = Z Y ,
where Y is nFR by mW, then the nZ nZ = nFR - mW columns of Z form a basis for the null space of AFR. Let nR be an integer such that 0≤nR≤nZ, and let ZR denote a matrix whose nR columns are a subset of the columns of Z. (The integer nR is the quantity Zr in the monitoring output from H02CBF. In many cases, ZR will include all the columns of Z.) The direction pFR will satisfy (2) if
pFR = ZR pR , (4)
where pR is any nR-vector.
Let Q denote the n by n matrix
Q= QFR IFX ,
where IFX is the identity matrix of order nFX. Let HQ and gQ denote the n by n transformed Hessian and transformed gradient
HQ=QT HQ  and  gQ=QT c+Hx
and let the matrix of first nR rows and columns of HQ be denoted by HR and the vector of the first nR elements of gQ be denoted by gR. The quantities HR and gR are known as the reduced Hessian and reduced gradient of f x, respectively. Roughly speaking, gR and HR describe the first and second derivatives of an unconstrained problem for the calculation of pR.
At each iteration, a triangular factorization of HR is available. If HR is positive definite, HR=RT R, where R is the upper triangular Cholesky factor of HR. If HR is not positive definite, HR=RT DR, where D=diag 1,1,…,1,μ, with μ≤0.
The computation is arranged so that the reduced-gradient vector is a multiple of eR, a vector of all zeros except in the last (i.e., nRth) position. This allows the vector pR in (4) to be computed from a single back-substitution
R pR=γ eR (5)
where γ is a scalar that depends on whether or not the reduced Hessian is positive definite at x. In the positive definite case, x+p is the minimizer of the objective function subject to the constraints (bounds and general) in the working set treated as equalities. If HR is not positive definite, pR satisfies the conditions
pRT HRpR<0  and   gRT pR≤0,
which allow the objective function to be reduced by any positive step of the form x+αp.

11.3 The Main Iteration

If the reduced gradient is zero, x is a constrained stationary point in the subspace defined by Z. During the feasibility phase, the reduced gradient will usually be zero only at a vertex (although it may be zero at non-vertices in the presence of constraint dependencies). During the optimality phase, a zero reduced gradient implies that x minimizes the quadratic objective when the constraints in the working set are treated as equalities. At a constrained stationary point, Lagrange-multipliers λC and λB for the general and bound constraints are defined from the equations
AFRT λC=gFR  and  λB=gFX-AFXT λC. (6)
Given a positive constant δ of the order of the machine precision, a Lagrange-multiplier λj corresponding to an inequality constraint in the working set is said to be optimal if λj≤δ when the associated constraint is at its upper bound, or if λj≥-δ when the associated constraint is at its lower bound. If a multiplier is nonoptimal, the objective function (either the true objective or the sum of infeasibilities) can be reduced by deleting the corresponding constraint (with index Jdel; see Section 13) from the working set.
If optimal multipliers occur during the feasibility phase and the sum of infeasibilities is nonzero, there is no feasible point, and you can force H02CBF to continue until the minimum value of the sum of infeasibilities has been found; see the discussion of the Minimum Sum of Infeasibilities in Section 12.1. At such a point, the Lagrange-multiplier λj corresponding to an inequality constraint in the working set will be such that -1+δ≤λj≤δ when the associated constraint is at its upper bound, and -δ≤λj≤1+δ when the associated constraint is at its lower bound. Lagrange-multipliers for equality constraints will satisfy λj≤1+δ.
If the reduced gradient is not zero, Lagrange-multipliers need not be computed and the nonzero elements of the search direction p are given by ZRpR (see (4) and (5)). The choice of step length is influenced by the need to maintain feasibility with respect to the satisfied constraints. If HR is positive definite and x+p is feasible, α will be taken as unity. In this case, the reduced gradient at x- will be zero, and Lagrange-multipliers are computed. Otherwise, α is set to αM, the step to the ‘nearest’ constraint (with index Jadd; see Section 13), which is added to the working set at the next iteration.
Each change in the working set leads to a simple change to AFR: if the status of a general constraint changes, a row of AFR is altered; if a bound constraint enters or leaves the working set, a column of AFR changes. Explicit representations are recurred of the matrices T, QFR and R; and of vectors QT g, and QT c. The triangular factor R associated with the reduced Hessian is only updated during the optimality phase.
One of the most important features of H02CBF is its control of the conditioning of the working set, whose nearness to linear dependence is estimated by the ratio of the largest to smallest diagonal elements of the TQ factor T (the printed value Cond T; see Section 13). In constructing the initial working set, constraints are excluded that would result in a large value of Cond T.
H02CBF includes a rigorous procedure that prevents the possibility of cycling at a point where the active constraints are nearly linearly dependent (see Gill et al. (1989)). The main feature of the anti-cycling procedure is that the feasibility tolerance is increased slightly at the start of every iteration. This not only allows a positive step to be taken at every iteration, but also provides, whenever possible, a choice of constraints to be added to the working set. Let αM denote the maximum step at which x+αM p does not violate any constraint by more than its feasibility tolerance. All constraints at a distance α (α≤αM) along p from the current point are then viewed as acceptable candidates for inclusion in the working set. The constraint whose normal makes the largest angle with the search direction is added to the working set.

11.4 Choosing the Initial Working Set

At the start of the optimality phase, a positive definite HR can be defined if enough constraints are included in the initial working set. (The matrix with no rows and columns is positive definite by definition, corresponding to the case when AFR contains nFR constraints.) The idea is to include as many general constraints as necessary to ensure that the reduced Hessian is positive definite.
Let HZ denote the matrix of the first nZ rows and columns of the matrix HQ=QT HQ at the beginning of the optimality phase. A partial Cholesky factorization is used to find an upper triangular matrix R that is the factor of the largest positive definite leading sub-matrix of HZ. The use of interchanges during the factorization of HZ tends to maximize the dimension of R. (The condition of R may be controlled using the Rank Tolerance. Let ZR denote the columns of Z corresponding to R, and let Z be partitioned as Z=ZRZA. A working set for which ZR defines the null space can be obtained by including the rows of ZAT as ‘artificial constraints’. Minimization of the objective function then proceeds within the subspace defined by ZR, as described in Section 11.2.
The artificially augmented working set is given by
A-FR= ZAT AFR , (7)
so that pFR will satisfy AFRpFR=0 and ZAT pFR=0. By definition of the TQ factorization, A-FR automatically satisfies the following:
A- FR QFR = ZAT AFR QFR = ZAT AFR ZR ZA Y = 0 T- ,
where
T- = I 0 0 T ,
and hence the TQ factorization of (7) is available trivially from T and QFR without additional expense.
The matrix ZA is not kept fixed, since its role is purely to define an appropriate null space; the TQ factorization can therefore be updated in the normal fashion as the iterations proceed. No work is required to ‘delete’ the artificial constraints associated with ZA when ZRT gFR=0, since this simply involves repartitioning QFR. The ‘artificial’ multiplier vector associated with the rows of ZAT is equal to ZAT gFR, and the multipliers corresponding to the rows of the ‘true’ working set are the multipliers that would be obtained if the artificial constraints were not present. If an artificial constraint is ‘deleted’ from the working set, an A appears alongside the entry in the Jdel column of the monitoring file output (see Section 13).
The number of columns in ZA and ZR, the Euclidean norm of ZRT gFR, and the condition estimator of R appear in the monitoring file output as Art, Zr, Norm Gz and Cond Rz respectively (see Section 13).
Under some circumstances, a different type of artificial constraint is used when solving a linear program. Although the algorithm of H02CBF does not usually perform simplex steps (in the traditional sense), there is one exception: a linear program with fewer general constraints than variables (i.e., mL≤n). (Use of the simplex method in this situation leads to savings in storage.) At the starting point, the ‘natural’ working set (the set of constraints exactly or nearly satisfied at the starting point) is augmented with a suitable number of ‘temporary’ bounds, each of which has the effect of temporarily fixing a variable at its current value. In subsequent iterations, a temporary bound is treated as a standard constraint until it is deleted from the working set, in which case it is never added again. If a temporary bound is ‘deleted’ from the working set, an F (for ‘Fixed’) appears alongside the entry in the Jdel column of the monitoring file output (see Section 13).

12 Optional Parameters

Several optional parameters in H02CBF define choices in the problem specification or the algorithm logic. In order to reduce the number of formal arguments of H02CBF these optional parameters have associated default values that are appropriate for most problems. Therefore, you need only specify those optional parameters whose values are to be different from their default values.
The remainder of this section can be skipped if you wish to use the default values for all optional parameters.
The following is a list of the optional parameters available. A full description of each optional parameter is provided in Section 12.1.
  • Check Frequency
  • Cold Start
  • Crash Tolerance
  • Defaults
  • Expand Frequency
  • Feasibility Phase Iteration Limit
  • Feasibility Tolerance
  • Hessian Rows
  • Infinite Bound Size
  • Infinite Step Size
  • Iteration Limit
  • Iters
  • Itns
  • List
  • Maximum Degrees of Freedom
  • Minimum Sum of Infeasibilities
  • Monitoring File
  • Nolist
  • Optimality Phase Iteration Limit
  • Optimality Tolerance
  • Print Level
  • Problem Type
  • Rank Tolerance
  • Warm Start
Optional parameters may be specified by calling one, or both, of the routines H02CCF and H02CDF prior to a call to H02CBF.
H02CCF reads options from an external options file, with Begin and End as the first and last lines respectively and each intermediate line defining a single optional parameter. For example,
Begin
  Print Level = 5
End
The call
CALL H02CCF(IOPTNS, INFORM)
can then be used to read the file on unit IOPTNS. INFORM will be zero on successful exit. H02CCF should be consulted for a full description of this method of supplying optional parameters.
H02CDF can be called to supply options directly, one call being necessary for each optional parameter. For example,
CALL H02CDF ('Print Level = 5')
H02CDF should be consulted for a full description of this method of supplying optional parameters.
All optional parameters not specified by you are set to their default values. Optional parameters specified by you are unaltered by H02CBF (unless they define invalid values) and so remain in effect for subsequent calls unless altered by you.

12.1 Description of the Optional Parameters

For each option, we give a summary line, a description of the optional parameter and details of constraints.
The summary line contains:
  • the keywords, where the minimum abbreviation of each keyword is underlined (if no characters of an optional qualifier are underlined, the qualifier may be omitted);
  • a parameter value, where the letters a, i and r denote options that take character, integer and real values respectively;
  • the default value, where the symbol ε is a generic notation for machine precision (see X02AJF).
Keywords and character values are case and white space insensitive.
Check Frequency i Default =50
Every ith iteration, a numerical test is made to see if the current solution x satisfies the constraints in the working set. If the largest residual of the constraints in the working set is judged to be too large, the current working set is refactorized and the variables are recomputed to satisfy the constraints more accurately. If i≤0, the default value is used.
Cold Start Default
Warm Start
This option specifies how the initial working set is chosen. With a Cold Start, H02CBF chooses the initial working set based on the values of the variables and constraints at the initial point. Broadly speaking, the initial working set will include equality constraints and bounds or inequality constraints that violate or ‘nearly’ satisfy their bounds (to within Crash Tolerance).
With a Warm Start, you must provide a valid definition of every element of the array ISTATE (see Section 5 for the definition of this array). H02CBF will override your specification of ISTATE if necessary, so that a poor choice of the working set will not cause a fatal error. For instance, any elements of ISTATE which are set to -2, -1​ or ​4 will be reset to zero, as will any elements which are set to 3 when the corresponding elements of BL and BU are not equal. A warm start will be advantageous if a good estimate of the initial working set is available – for example, when H02CBF is called repeatedly to solve related problems.
Crash Tolerance r Default =0.01
This value is used in conjunction with the optional parameter Cold Start (the default value) when H02CBF selects an initial working set. If 0≤r≤1, the initial working set will include (if possible) bounds or general inequality constraints that lie within r of their bounds. In particular, a constraint of the form ajT x≥l will be included in the initial working set if ajT x-l ≤ r 1+l . If r<0 or r>1, the default value is used.
Defaults
This special keyword may be used to reset all optional parameters to their default values.
Expand Frequency i Default =5
This option is part of an anti-cycling procedure designed to guarantee progress even on highly degenerate problems.
The strategy is to force a positive step at every iteration, at the expense of violating the constraints by a small amount. Suppose that the value of the optional parameter Feasibility Tolerance is δ. Over a period of i iterations, the feasibility tolerance actually used by H02CBF (i.e., the working feasibility tolerance) increases from 0.5 δ to δ (in steps of 0.5 δ/i).
At certain stages the following ‘resetting procedure’ is used to remove constraint infeasibilities. First, all variables whose upper or lower bounds are in the working set are moved exactly onto their bounds. A count is kept of the number of nontrivial adjustments made. If the count is positive, iterative refinement is used to give variables that satisfy the working set to (essentially) machine precision. Finally, the working feasibility tolerance is reinitialized to 0.5 δ.
If a problem requires more than i iterations, the resetting procedure is invoked and a new cycle of i iterations is started with i incremented by 10. (The decision to resume the feasibility phase or optimality phase is based on comparing any constraint infeasibilities with δ.)
The resetting procedure is also invoked when H02CBF reaches an apparently optimal, infeasible or unbounded solution, unless this situation has already occurred twice. If any nontrivial adjustments are made, iterations are continued.
If i≤0, the default value is used. If i≥9999999, no anti-cycling procedure is invoked.
Feasibility Phase Iteration Limit i 1 Default =max 50,5 n+mL
Optimality Phase Iteration Limit i 2 Default =max 50,5 n+mL
The scalars i 1 and i 2 specify the maximum number of iterations allowed in the feasibility and optimality phases. Optimality Phase Iteration Limit is equivalent to Iteration Limit. Setting i 1=0 and Print Level>0 means that the workspace needed will be computed and printed, but no iterations will be performed. If i 1<0 or i 2<0, the default value is used.
Feasibility Tolerance r Default =ε
If r≥ε, r defines the maximum acceptable absolute violation in each constraint at a ‘feasible’ point. For example, if the variables and the coefficients in the general constraints are of order unity, and the latter are correct to about 6 decimal digits, it would be appropriate to specify r as 10-6. If 0≤r<ε, the default value is used.
H02CBF attempts to find a feasible solution before optimizing the objective function. If the sum of infeasibilities cannot be reduced to zero, the Minimum Sum of Infeasibilities can be used to find the minimum value of the sum. Let Sinf be the corresponding sum of infeasibilities. If Sinf is quite small, it may be appropriate to raise r by a factor of 10 or 100. Otherwise, some error in the data should be suspected.
Note that a ‘feasible solution’ is a solution that satisfies the current constraints to within the tolerance r.
Hessian Rows i Default =n
Note that this option does not apply to problems of type FP or LP.
This specifies m, the number of rows of the Hessian matrix H. The default value of m is n, the number of variables of the problem.
If the problem is of type QP, m will usually be n, the number of variables. However, a value of m less than n is appropriate for QP3 or QP4 if H is an upper trapezoidal matrix with m rows. Similarly, m may be used to define the dimension of a leading block of nonzeros in the Hessian matrices of QP1 or QP2, in which case the last n-m rows and columns of H are assumed to be zero. In the QP case, m should not be greater than n; if it is, the last m-n rows of H are ignored.
If i<0 or i>n, the default value is used.
Infinite Bound Size r Default =1020
If r>0, r defines the ‘infinite’ bound bigbnd in the definition of the problem constraints. Any upper bound greater than or equal to bigbnd will be regarded as +∞ (and similarly any lower bound less than or equal to -bigbnd will be regarded as -∞). If r≤0, the default value is used.
Infinite Step Size r Default =max bigbnd,1020
If r>0, r specifies the magnitude of the change in variables that will be considered a step to an unbounded solution. (Note that an unbounded solution can occur only when the Hessian is not positive definite.) If the change in x during an iteration would exceed the value of r, the objective function is considered to be unbounded below in the feasible region. If r≤0, the default value is used.
Iteration Limit i Default =max 50,5 n+mL
Iters
Itns
See optional parameter Feasibility Phase Iteration Limit.
List Default
Nolist
Normally each optional parameter specification is printed as it is supplied. Optional parameter Nolist may be used to suppress the printing and optional parameter List may be used to restore printing.
Maximum Degrees of Freedom i Default =n
Note that this option does not apply to problems of type FP or LP.
This places a limit on the storage allocated for the triangular factor R of the reduced Hessian HR. Ideally, i should be set slightly larger than the value of nR expected at the solution. It need not be larger than mN+1, where mN is the number of variables that appear nonlinearly in the quadratic objective function. For many problems it can be much smaller than mN.
For quadratic problems, a minimizer may lie on any number of constraints, so that nR may vary between 1 and n. The default value of i is therefore the number of variables n. If Hessian Rows m is specified, the default value of i is the same number, m.
Minimum Sum of Infeasibilities Default =NO
If no feasible point exists for the constraints, this option is used to control whether or not H02CBF will calculate a point that minimizes the constraint violations. If Minimum Sum of Infeasibilities=N O, H02CBF will terminate as soon as it is evident that no feasible point exists for the constraints. The final point will generally not be the point at which the sum of infeasibilities is minimized. If Minimum Sum of Infeasibilities=Y ES, H02CBF will continue until the sum of infeasibilities is minimized.
Monitoring File i Default =-1
If i≥0 and Print Level≥5, monitoring information produced by H02CBF at every iteration is sent to a file with logical unit number i. If i<0 and/or Print Level<5, no monitoring information is produced.
Optimality Tolerance r Default =ε 0.8
If r≥ε, r defines the tolerance used to determine if the bounds and general constraints have the right ‘sign’ for the solution to be judged to be optimal.
If 0≤r<ε, the default value is used.
Print Level i Default =10
The value of i controls the amount of printout produced by H02CBF, as indicated below. A detailed description of the printed output is given in Section 9.2 (summary output at each iteration and the final solution) and Section 13 (monitoring information at each iteration). If i<0, the default value is used.
The following printout is sent to the current advisory message unit (as defined by X04ABF):
≥i | Output
≥0 0 | No output.
≥0 1 | The final solution only.
≥0 5 | One line of summary output (<80 characters; see Section 9.2) for each iteration (no printout of the final solution).
≥10 | The final solution and one line of summary output for each iteration.
The following printout is sent to the logical unit number defined by the Monitoring File:
≥i | Output
<5 | No output.
≥5 | One long line of output (>80 characters; see Section 13) for each iteration (no printout of the final solution).
≥20 | At each iteration, the Lagrange-multipliers, the variables x, the constraint values Ax and the constraint status.
≥30 | At each iteration, the diagonal elements of the upper triangular matrix T associated with the TQ factorization (3) (see Section 11.2) of the working set, and the diagonal elements of the upper triangular matrix R.
If Print Level≥5 and the unit number defined by Monitoring File is the same as that defined by X04ABF, then the summary output is suppressed.
Problem Type a Default = QP2
This option specifies the type of objective function to be minimized during the optimality phase. The following are the five optional keywords and the dimensions of the arrays that must be specified in order to define the objective function:
LP | H not referenced, CVEC N required;
QP1 | H LDH* symmetric, CVEC not referenced;
QP2 | H LDH* symmetric, CVEC N required;
QP3 | H LDH* upper trapezoidal, CVEC not referenced;
QP4 | H LDH* upper trapezoidal, CVEC N required.
For problems of type FP, the objective function is omitted and neither H nor CVEC are referenced.
The following keywords are also acceptable. The minimum abbreviation of each keyword is underlined.
a | Option
Quadratic | QP2
Linear | LP
Feasible | FP
In addition, the keyword QP is equivalent to the default option QP2.
If H=0, i.e., the objective function is purely linear, the efficiency of H02CBF may be increased by specifying a as LP.
Rank Tolerance r Default =100 ε
Note that this option does not apply to problems of type FP or LP.
This parameter enables you to control the condition number of the triangular factor R (see Section 11). If ρi denotes the function ρi=max R 11,R 22,…,R ii, the dimension of R is defined to be smallest index i such that R i+1,i+1≤r ρ i+1. If r≤0, the default value is used.

13 Description of Monitoring Information

This section describes the long line of output (>80 characters) which forms part of the monitoring information produced by H02CBF. (See also the description of the optional parameters Monitoring File and Print Level in Section 12.1.) You can control the level of printed output.
To aid interpretation of the printed results, the following convention is used for numbering the constraints: indices 1 through n refer to the bounds on the variables, and indices n+1 through n+mL refer to the general constraints. When the status of a constraint changes, the index of the constraint is printed, along with the designation L (lower bound), U (upper bound), E (equality), F (temporarily fixed variable) or A (artificial constraint).
When Print Level≥5 and Monitoring File≥0, the following line of output is produced at every iteration on the unit number specified by Monitoring File. In all cases, the values of the quantities printed are those in effect on completion of the given iteration.
Itn | is the iteration count.
Jdel | is the index of the constraint deleted from the working set. If Jdel is zero, no constraint was deleted.
Jadd | is the index of the constraint added to the working set. If Jadd is zero, no constraint was added.
Step | is the step taken along the computed search direction. If a constraint is added during the current iteration, Step will be the step to the nearest constraint. When the problem is of type LP, the step can be greater than one during the optimality phase.
Ninf | is the number of violated constraints (infeasibilities). This will be zero during the optimality phase.
Sinf/Objective | is the value of the current objective function. If x is not feasible, Sinf gives a weighted sum of the magnitudes of constraint violations. If x is feasible, Objective is the value of the objective function. The output line for the final iteration of the feasibility phase (i.e., the first iteration for which Ninf is zero) will give the value of the true objective at the first feasible point. During the optimality phase, the value of the objective function will be nonincreasing. During the feasibility phase, the number of constraint infeasibilities will not increase until either a feasible point is found, or the optimality of the multipliers implies that no feasible point exists. Once optimal multipliers are obtained, the number of infeasibilities can increase, but the sum of infeasibilities will either remain constant or be reduced until the minimum sum of infeasibilities is found.
Bnd | is the number of simple bound constraints in the current working set.
Lin | is the number of general linear constraints in the current working set.
Art | is the number of artificial constraints in the working set, i.e., the number of columns of ZA (see Section 11.4).
Zr | is the number of columns of ZR (see Section 11.2). Zr is the dimension of the subspace in which the objective function is currently being minimized. The value of Zr is the number of variables minus the number of constraints in the working set; i.e., Zr=n-Bnd+Lin+Art. The value of nZ, the number of columns of Z (see Section 11.2) can be calculated as nZ=n-Bnd+Lin. A zero value of nZ implies that x lies at a vertex of the feasible region.
Norm Gz | is ZRT gFR , the Euclidean norm of the reduced gradient with respect to ZR (see Sections 11.2 and 11.4). During the optimality phase, this norm will be approximately zero after a unit step.
NOpt | is the number of nonoptimal Lagrange-multipliers at the current point. NOpt is not printed if the current x is infeasible or no multipliers have been calculated. At a minimizer, NOpt will be zero.
Min Lm | is the value of the Lagrange-multiplier associated with the deleted constraint. If Min Lm is negative, a lower bound constraint has been deleted, if Min Lm is positive, an upper bound constraint has been deleted. If no multipliers are calculated during a given iteration, Min Lm will be zero.
Cond T | is a lower bound on the condition number of the working set.
Cond Rz | is a lower bound on the condition number of the triangular factor R (the Cholesky factor of the current reduced Hessian; see Section 11.2). If the problem is specified to be of type LP, Cond Rz is not printed.
Rzz | is the last diagonal element μ of the matrix D associated with the RT DR factorization of the reduced Hessian HR (see Section 11.2). Rzz is only printed if HR is not positive definite (in which case μ≠1). If the printed value of Rzz is small in absolute value, then HR is approximately singular. A negative value of Rzz implies that the objective function has negative curvature on the current working set.
H Chapter Contents
H Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


H02CCF : NAG Library, Mark 26

H Chapter Contents
H Chapter Introduction
NAG Library Manual

NAG Library Routine Document

H02CCF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

To supply optional parameters to H02CBF from an external file.

2 Specification

SUBROUTINE H02CCF ( IOPTNS, INFORM)
INTEGER IOPTNS, INFORM

3 Description

H02CCF may be used to supply values for optional parameters to H02CBF. H02CCF reads an external file and each line of the file defines a single optional parameter. It is only necessary to supply values for those arguments whose values are to be different from their default values.
Each optional parameter is defined by a single character string of up to 72 characters, consisting of one or more items. The items associated with a given option must be separated by spaces, or equal signs =. Alphabetic characters may be upper or lower case. The string
 Print level = 1
is an example of a string used to set an optional parameter. For each option the string contains one or more of the following items:
– | a mandatory keyword;
– | a phrase that qualifies the keyword;
– | a number that specifies an integer or real value. Such numbers may be up to 16 contiguous characters in Fortran 77's I, F, E or D formats, terminated by a space if this is not the last item on the line.
Blank strings and comments are ignored. A comment begins with an asterisk (*) and all subsequent characters in the string are regarded as part of the comment.
The file containing the options must start with Begin and must finish with End. An example of a valid options file is:
Begin * Example options file
 Print level = 10
End
Normally each line of the file is printed as it is read, on the current advisory message unit (see X04ABF), but printing may be suppressed using the keyword Nolist. To suppress printing of Begin, Nolist must be the first option supplied as in the file:
Begin
 Nolist
 Print level = 10
End
Printing will automatically be turned on again after a call to H02CBF and may be turned on again at any time by you by using the keyword List.
Optional parameter settings are preserved following a call to H02CBF, and so the keyword Defaults is provided to allow you to reset all the optional parameters to their default values prior to a subsequent call to H02CBF.
A complete list of optional parameters, their abbreviations, synonyms and default values is given in Section 12 in H02CBF.

4 References

None.

5 Arguments

1:   IOPTNS – INTEGERInput
On entry: the unit number of the options file to be read.
Constraint: 0≤IOPTNS≤99.
2:   INFORM – INTEGEROutput
On exit: contains zero if the options file has been successfully read and a value >0 otherwise, as indicated below.
INFORM=1
IOPTNS is not in the range 0,99.
INFORM=2
Begin was found, but end-of-file was found before End was found.
INFORM=3
end-of-file was found before Begin was found.

6 Error Indicators and Warnings

If a line is not recognized as a valid option, then a warning message is output on the current advisory message unit (see X04ABF).

7 Accuracy

Not applicable.

8 Parallelism and Performance

H02CCF is not thread safe and should not be called from a multithreaded user program. Please see Section 3.12.1 in How to Use the NAG Library and its Documentation for more information on thread safety.
H02CCF is not threaded in any implementation.

9 Further Comments

H02CDF may also be used to supply optional parameters to H02CBF. Note that if E04NFF/E04NFA is used in the same program as H02CBF, then in general H02CCF will also affect the options used by E04NFF/E04NFA.

10 Example

This example solves the same problem as the example for H02CBF, but in addition illustrates the use of H02CCF and H02CDF to set optional parameters for H02CBF.
In this example the options file read by H02CCF is appended to the data file for the program (see Section 10.2). It would usually be more convenient in practice to keep the data file and the options file separate.

10.1 Program Text

Program Text (h02ccfe.f90)

10.2 Program Data

Program Options (h02ccfe.opt)

Program Data (h02ccfe.d)

10.3 Program Results

Program Results (h02ccfe.r)

H Chapter Contents
H Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


H02CDF : NAG Library, Mark 26

H Chapter Contents
H Chapter Introduction
NAG Library Manual

NAG Library Routine Document

H02CDF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

To supply individual optional parameters to H02CBF.

2 Specification

SUBROUTINE H02CDF ( STR)
CHARACTER(*) STR

3 Description

H02CDF may be used to supply values for optional parameters to H02CBF. It is only necessary to call H02CDF for those arguments whose values are to be different from their default values. One call to H02CDF sets one argument value.
Each optional parameter is defined by a single character string of up to 72 characters, consisting of one or more items. The items associated with a given option must be separated by spaces, or equal signs =. Alphabetic characters may be upper or lower case. The string
 Print level = 1
is an example of a string used to set an optional parameter. For each option the string contains one or more of the following items:
– | a mandatory keyword;
– | a phrase that qualifies the keyword;
– | a number that specifies an integer or real value. Such numbers may be up to 16 contiguous characters in Fortran 77's I, F, E or D formats, terminated by a space if this is not the last item on the line.
Blank strings and comments are ignored. A comment begins with an asterisk (*) and all subsequent characters in the string are regarded as part of the comment.
Normally, each user-specified option is printed as it is defined, on the current advisory message unit (see X04ABF), but this printing may be suppressed using the keyword Nolist. Thus the statement
CALL H02CDF ('Nolist')
suppresses printing of this and subsequent options. Printing will automatically be turned on again after a call to H02CBF, and may be turned on again at any time by you, by using the keyword List.
Optional parameter settings are preserved following a call to H02CBF, and so the keyword Defaults is provided to allow you to reset all the optional parameters to their default values by the statement,
CALL H02CDF ('Defaults')
prior to a subsequent call to H02CBF.
A complete list of optional parameters, their abbreviations, synonyms and default values is given in Section 12 in H02CBF.

4 References

None.

5 Arguments

1:   STR – CHARACTER(*)Input
On entry: a single valid option string (as described in Section 3 above and in Section 12 in H02CBF).

6 Error Indicators and Warnings

If a line is not recognized as a valid option, then a warning message is output on the current advisory message unit (see X04ABF).

7 Accuracy

Not applicable.

8 Parallelism and Performance

H02CDF is not thread safe and should not be called from a multithreaded user program. Please see Section 3.12.1 in How to Use the NAG Library and its Documentation for more information on thread safety.
H02CDF is not threaded in any implementation.

9 Further Comments

H02CCF may also be used to supply optional parameters to H02CBF. Note that if E04NFF/E04NFA is used in the same program as H02CBF, then in general H02CCF will also affect the options used by E04NFF/E04NFA.

10 Example

See Section 10 in H02CCF.
H Chapter Contents
H Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


H02CEF : NAG Library, Mark 26

H Chapter Contents
H Chapter Introduction
NAG Library Manual

NAG Library Routine Document

H02CEF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.
Note: this routine uses optional parameters to define choices in the problem specification and in the details of the algorithm. If you wish to use default settings for all of the optional parameters, you need only read Sections 1 to 10 of this document. If, however, you wish to reset some or all of the settings please refer to Section 11 for a detailed description of the algorithm, to Section 12 for a detailed description of the specification of the optional parameters and to Section 13 for a detailed description of the monitoring information produced by the routine.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
▸▿ 9 Further Comments
9.1 Description of the Printed Output
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results
▸▿ 11 Algorithmic Details
11.1 Overview
11.2 Definition of the Working Set and Search Direction
11.3 The Main Iteration
11.4 Miscellaneous
▸▿ 12 Optional Parameters
12.1 Description of the Optional Parameters
13 Description of Monitoring Information

1 Purpose

H02CEF obtains integer solutions to sparse linear programming and quadratic programming problems.

2 Specification

SUBROUTINE H02CEF ( N, M, NNZ, IOBJ, NCOLH, QPHX, A, HA, KA, BL, BU, START, NAMES, NNAME, CRNAME, NS, XS, INTVAR, LINTVR, MDEPTH, ISTATE, MINIZ, MINZ, OBJ, CLAMDA, STRTGY, IZ, LENIZ, Z, LENZ, MONIT, IFAIL)
INTEGER | N, M, NNZ, IOBJ, NCOLH, HA(NNZ), KA(N+1), NNAME, NS, INTVAR(LINTVR), LINTVR, MDEPTH, ISTATE(N+M), MINIZ, MINZ, STRTGY, IZ(LENIZ), LENIZ, LENZ, IFAIL
REAL (KIND=nag_wp) | A(NNZ), BL(N+M), BU(N+M), XS(N+M), OBJ, CLAMDA(N+M), Z(LENZ)
CHARACTER(1) | START
CHARACTER(8) | NAMES(5), CRNAME(NNAME)
EXTERNAL | QPHX, MONIT

3 Description

H02CEF is designed to obtain integer solutions to a class of quadratic programming problems addressed by E04NKF/E04NKA. Specifically it solves the following problem:
minimize x∈Rn f x  subject to  l≤ x Ax ≤ u, (1)
where x=x 1,x 2,…,xn T is a set of variables (some of which may be required to be integer), A is an m by n matrix and the objective function f x may be specified in a variety of ways depending upon the particular problem to be solved. The optional parameter Maximize may be used to specify an alternative problem in which f x is maximized. The possible forms for f x are listed in Table 1, in which the prefixes LP and QP stand for ‘linear programming’ and ‘quadratic programming’ respectively, c is an n-element vector and H is the n by n second-derivative matrix ∇2 f x (the Hessian matrix).
Problem type | Objective function f x | Hessian matrix H
LP | cT x | Not applicable
QP | cT x+12 xT Hx | Symmetric positive semidefinite
Table 1
For LP and QP problems, the unique global minimum value of f x is found. For QP problems, you must also provide a subroutine that computes Hx for any given vector x. (H need not be stored explicitly.)
(It is not expected that the feasibility problem of E04NKF/E04NKA would be relevant here.)
The routine employs a ‘Branch and Bound’ technique to enforce the integer constraints. In this technique the problem is first solved without the integer constraints. If a variable is found to be non-integral when it is required to have an integer value then two additional problems are constructed. One bounds the variable above by the nearest integer value below the optimal value previously obtained. The second problem is formed by bounding the variable below by the nearest integer value above the optimal value. This process is continued until an integer solution is found. At this point you may elect to stop, or may continue to search for better integer solutions by examining any other sub-problems that remain to be explained.
In practice the routine tries to compute an integer solution as quickly as possible using a depth-first approach, since this helps determine a realistic cut-off value. If we have a cut-off value, say the value of the function at this first integer solution, and any sub-problem, W say, has a solution value greater than this cut-off value, then subsequent sub-problems of W must have solutions greater than the value of the solution at W and therefore need not be computed. Thus a knowledge of a good cut-off value can result in fewer sub-problems being solved and thus speed up the operation of the routine. (See the description of MONIT in Section 5 for details of how you can supply your own cut-off value.)
Each sub-problem is solved using E04NKA. You are referred to the routine document for E04NKF/E04NKA for details of the algorithm used.

4 References

Gill P E, Hammarling S, Murray W, Saunders M A and Wright M H (1986) Users' guide for LSSOL (Version 1.0) Report SOL 86-1 Department of Operations Research, Stanford University
Gill P E and Murray W (1978) Numerically stable methods for quadratic programming Math. Programming 14 349–372
Gill P E, Murray W, Saunders M A and Wright M H (1986) Some theoretical properties of an augmented Lagrangian merit function Report SOL 86–6R Department of Operations Research, Stanford University
Gill P E, Murray W, Saunders M A and Wright M H (1989) A practical anti-cycling procedure for linearly constrained optimization Math. Programming 45 437–474
Gill P E, Murray W, Saunders M A and Wright M H (1991) Inertia-controlling methods for general quadratic programming SIAM Rev. 33 1–36
Hock W and Schittkowski K (1981) Test Examples for Nonlinear Programming Codes. Lecture Notes in Economics and Mathematical Systems 187 Springer–Verlag
Lawson C L, Hanson R J, Kincaid D R and Krogh F T (1979) Basic linear algebra supbrograms for Fortran usage ACM Trans. Math. Software 5 308–325
Murtagh B A and Saunders M A (1983) MINOS 5.0 user's guide Report SOL 83-20 Department of Operations Research, Stanford University

5 Arguments

1:   N – INTEGERInput
On entry: n, the number of variables (excluding slacks). This is the number of columns in the linear constraint matrix A.
Constraint: N≥1.
2:   M – INTEGERInput
On entry: m, the number of general linear constraints (or slacks). This is the number of rows in A, including the free row (if any; see IOBJ).
Constraint: M≥1.
3:   NNZ – INTEGERInput
On entry: the number of nonzero elements in A.
Constraint: 1≤NNZ≤N×M.
4:   IOBJ – INTEGERInput
On entry: if IOBJ>0, row IOBJ of A is a free row containing the nonzero elements of the vector c appearing in the linear objective term cT x.
If IOBJ=0, there is no free row, i.e., the problem is either an FP problem (in which case IOBJ must be set to zero), or a QP problem with c=0.
Constraint: 0≤IOBJ≤M.
5:   NCOLH – INTEGERInput
On entry: nH, the number of leading nonzero columns of the Hessian matrix H. For FP and LP problems, NCOLH must be set to zero.
Constraint: 0≤NCOLH≤N.
6:   QPHX – SUBROUTINE, supplied by the NAG Library or the user.External Procedure
For QP problems, you must supply a version of QPHX to compute the matrix product Hx. If H has rows and columns consisting entirely of zeros, it is most efficient to order the variables x=y z T so that
Hx= H 1 0 0 0 y z = H 1 y 0 ,
where the nonlinear variables y appear first as shown. For LP problems, QPHX will never be called by H02CEF.
The specification of QPHX is:
SUBROUTINE QPHX ( NSTATE, NCOLH, X, HX)
INTEGER | NSTATE, NCOLH
REAL (KIND=nag_wp) | X(NCOLH), HX(NCOLH)
1:   NSTATE – INTEGERInput
On entry: if NSTATE=1, then H02CEF is calling QPHX for the first time on a sub-problem. This argument setting allows you to save computation time if certain data must be read or calculated only once.
If NSTATE≥2, then H02CEF is calling QPHX for the last time. This argument setting allows you to perform some additional computation on the final sub-problem solution. In general, the last call to QPHX is made with NSTATE=2+IFAIL (see Section 6).
Otherwise, NSTATE=0.
2:   NCOLH – INTEGERInput
On entry: this is the same argument NCOLH as supplied to H02CEF.
3:   X NCOLH – REAL (KIND=nag_wp) arrayInput
On entry: the first NCOLH elements of the vector x.
4:   HX NCOLH – REAL (KIND=nag_wp) arrayOutput
On exit: the product Hx.
QPHX must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which H02CEF is called. Arguments denoted as Input must not be changed by this procedure.
7:   A NNZ – REAL (KIND=nag_wp) arrayInput
On entry: the nonzero elements of A, ordered by increasing column index. Note that multiple elements with the same row and column indices are not allowed.
On exit: used as internal workspace prior to being restored and hence is unchanged.
8:   HA NNZ – INTEGER arrayInput
On entry: HA i must contain the row index of the nonzero element stored in A i, for i=1,2,…,NNZ. Note that the row indices for a column may be supplied in any order.
Constraint: 1≤HA i≤M, for i=1,2,…,NNZ.
9:   KA N+1 – INTEGER arrayInput
On entry: KA j must contain the index in A of the start of the jth column, for j=1,2,…,N. To specify the jth column as empty, set KA j=KA j+1. Note that the first and last elements of KA must be such that KA 1=1 and KA N+1=NNZ+1.
Constraints:
  • KA 1=1;
  • KA j≥1, for j=2,3,…,N;
  • KA N+1=NNZ+1;
  • 0≤KA j+1-KA j≤M, for j=1,2,…,N.
10:   BL N+M – REAL (KIND=nag_wp) arrayInput
On entry: l, the lower bounds for all the variables and general constraints, in the following order. The first N elements of BL must contain the bounds on the variables x, and the next M elements the bounds for the general linear constraints Ax (or slacks s) and the free row (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set BL j≤-bigbnd, where bigbnd is the value of the optional parameter Infinite Bound Size (default value=1020). To specify the jth constraint as an equality, set BL j=BU j=β, say, where β<bigbnd. Note that the lower bound corresponding to the free row must be set to -∞ and stored in BL N+IOBJ.
Constraint: if IOBJ>0, BL N+IOBJ≤-bigbnd
(See also the description for BU.)
11:   BU N+M – REAL (KIND=nag_wp) arrayInput
On entry: u, the upper bounds for all the variables and general constraints, in the following order. The first N elements of BL must contain the bounds on the variables x, and the next M elements the bounds for the general linear constraints Ax (or slacks s) and the free row (if any). To specify a nonexistent upper bound (i.e., uj=+∞), set BU j≥bigbnd. Note that the upper bound corresponding to the free row must be set to +∞ and stored in BU N+IOBJ.
On exit: used as internal workspace prior to being restored and hence is unchanged.
Constraints:
  • if IOBJ>0, BU N+IOBJ≥bigbnd;
  • BL j≤BU j, for j=1,2,…,N+M;
  • if BL j=BU j=β, β<bigbnd.
12:   START – CHARACTER(1)Input
On entry: indicates how a starting basis is to be obtained.
START='C'
An internal crash procedure will be used to choose an initial basis matrix B.
START='W'
A basis is already defined in ISTATE (probably from a previous call).
Constraint: START='C' or 'W'.
13:   NAMES 5 – CHARACTER(8) arrayInput
On entry: a set of names associated with the so-called MPSX form of the problem.
NAMES 1
Must contain the name for the problem (or be blank).
NAMES 2
Must contain the name for the free row (or be blank).
NAMES 3
Must contain the name for the constraint right-hand side (or be blank).
NAMES 4
Must contain the name for the ranges (or be blank).
NAMES 5
Must contain the name for the bounds (or be blank).
(These names are used in the monitoring file output; see Section 13.)
14:   NNAME – INTEGERInput
On entry: the number of column (i.e., variable) and row names supplied in the array NAMES.
NNAME=1
There are no names. Default names will be used in the printed output.
NNAME=N+M
All names must be supplied.
Constraint: NNAME=1 or N+M.
15:   CRNAME NNAME – CHARACTER(8) arrayInput
On entry: the optional column and row names.
If NNAME=1, CRNAME is not referenced and the printed output will use default names for the columns and rows.
If NNAME=N+M, the first N elements must contain the names for the columns and the next M elements must contain the names for the rows. Note that the name for the free row (if any) must be stored in CRNAME N+IOBJ.
16:   NS – INTEGERInput/Output
On entry: nS, the number of superbasics. For QP problems, NS need not be specified if START='C', but must retain its value from a previous call when START='W'. For FP and LP problems, NS need not be initialized.
On exit: the final number of superbasics. This will be zero for FP and LP problems.
17:   XS N+M – REAL (KIND=nag_wp) arrayInput/Output
On entry: the initial values of the variables and slacks x,s. (See the description for ISTATE.)
On exit: XS i contains the final value of xi, for i=1,2,…,n.
18:   INTVAR LINTVR – INTEGER arrayInput
On entry: specifies which components of the solution vector x are constrained to be integer. Specifically, if k elements of x are required to take integer values then INTVAR i=li, for i=1,2,…,k, where li is the integer index such that x li is integer. If k<LINTVR then INTVAR k+1 must be set to -1 to signal the end of the integer variable indices.
The order in which the indices of those components of x required to be integer is presented determines the order in which the sub-problems are treated and solved. As such it can be a powerful tool to assist the routine in achieving a solution efficiently. The general advice is to enter the important integer variables in the model early in INTVAR; secondary or less important variables should be entered near the end of the list. However some experimentation might be required to find the optimal order.
19:   LINTVR – INTEGERInput
On entry: k, the number of components of x required to be integer. If k=0, then LINTVR must be set to 1 and INTVAR 1 set to -1.
20:   MDEPTH – INTEGERInput
On entry: specifies the maximum depth the tree of sub-problems may be developed.
Suggested value: MDEPTH=2×N+20.
Constraint: MDEPTH>0.
21:   ISTATE N+M – INTEGER arrayInput/Output
On entry: if START='C', the first N elements of ISTATE and XS must specify the initial states and values, respectively, of the variables x. (The slacks s need not be initialized.) An internal crash procedure is then used to select an initial basis matrix B. The initial basis matrix will be triangular (neglecting certain small elements in each column). It is chosen from various rows and columns of columns of A-I. Possible values for ISTATE j are as follows:
ISTATE j | State of XS j during crash procedure
0 or 1 | Eligible for the basis
2 | Ignored
3 | Eligible for the basis (given preference over 0 or 1)
4 or 5 | Ignored
If nothing special is known about the problem, or there is no wish to provide special information, you may set ISTATE j=0 and XS j=0.0, for j=1,2,…,N. All variables will then be eligible for the initial basis. Less trivially, to say that the jth variable will probably be equal to one of its bounds, set ISTATE j=4 and XS j=BL j or ISTATE j=5 and XS j=BU j as appropriate.
Following the crash procedure, variables for which ISTATE j=2 are made superbasic. Other variables not selected for the basis are then made nonbasic at the value XS j if BL j≤XS j≤BU j, or at the value BL j or BU j closest to XS j.
If START='W', ISTATE and XS must specify the initial states and values, respectively, of the variables and slacks x,s. If H02CEF has been called previously with the same values of N and M, ISTATE already contains satisfactory information.
Constraints:
  • if START='C', 0≤ISTATE j≤5, for j=1,2,…,N;
  • if START='W', 0≤ISTATE j≤3, for j=1,2,…,N+M.
On exit: the final states of the variables and slacks x,s from the solution of the last sub-problem tackled. The significance of each possible value of ISTATE j is as follows:
ISTATE j | State of variable j | Normal value of XS j
0 | Nonbasic | BL j
1 | Nonbasic | BU j
2 | Superbasic | Between BL j and BU j
3 | Basic | Between BL j and BU j
If Ninf=0 (see Section 9.1), basic and superbasic variables may be outside their bounds by as much as the value of the optional parameter Feasibility Tolerance (default value=max 10-6,ε, where ε is the machine precision). Note that unless the optional parameter Scale Option=0 (default value=2) is specified, the Feasibility Tolerance applies to the variables of the scaled problem. In this case, the variables of the original problem may be as much as 0.1 outside their bounds, but this is unlikely unless the problem is very badly scaled.
Very occasionally some nonbasic variables may be outside their bounds by as much as the Feasibility Tolerance, and there may be some nonbasic variables for which XS j lies strictly between its bounds.
If Ninf>0, some basic and superbasic variables may be outside their bounds by an arbitrary amount (bounded by Sinf (see Section 9.1) if Scale Option=0).
22:   MINIZ – INTEGEROutput
On exit: the minimum value of LENIZ required to start solving the problem. If IFAIL=14, H02CEF may be called again with LENIZ suitably larger than MINIZ. (The bigger the better, since it is not certain how much workspace the basis factors need.)
23:   MINZ – INTEGEROutput
On exit: the minimum value of LENZ required to start solving the problem. If IFAIL=15, H02CEF may be called again with LENZ suitably larger than MINZ. (The bigger the better, since it is not certain how much workspace the basis factors need.)
24:   OBJ – REAL (KIND=nag_wp)Output
On exit: the value of the objective function.
If Ninf=0, OBJ includes the quadratic objective term 12 xT Hx (if any).
If Ninf >0, OBJ is just the linear objective term cT x (if any). For FP problems, OBJ is set to zero.
25:   CLAMDA N+M – REAL (KIND=nag_wp) arrayOutput
On exit: a set of Lagrange-multipliers for the bounds on the variables and the general constraints. More precisely, the first N elements contain the multipliers (reduced costs) for the bounds on the variables, and the next M elements contain the multipliers (shadow prices) for the general linear constraints.
26:   STRTGY – INTEGERInput
On entry: defines the branching strategy adopted by the routine.
STRTGY=0
Each sub-problem first explored imposes a tighter upper bound on the component of x.
STRTGY=1
Each sub-problem first explored imposes a tighter lower bound on the component of x.
STRTGY=2
Each branch explored imposes a tighter upper bound on the component of x if its fractional part is less than 0.5, otherwise it imposes a tighter lower bound.
STRTGY=3
Random choice is made between first exploring a tighter lower bound or a tighter upper bound sub-problem.
Constraint: STRTGY=0, 1, 2 or 3.
27:   IZ LENIZ – INTEGER arrayWorkspace
28:   LENIZ – INTEGERInput
On entry: the dimension of the array IZ as declared in the (sub)program from which H02CEF is called.
Constraint: LENIZ≥1.
29:   Z LENZ – REAL (KIND=nag_wp) arrayWorkspace
30:   LENZ – INTEGERInput
On entry: the dimension of the array Z as declared in the (sub)program from which H02CEF is called.
Constraint: LENZ≥1.
The amounts of workspace provided (i.e., LENIZ and LENZ) and required (i.e., MINIZ and MINZ) are (by default) output on the current advisory message unit (as defined by X04ABF). Since the minimum values of LENIZ and LENZ required to start solving the problem are returned in MINIZ and MINZ, respectively, you may prefer to obtain appropriate values from the output of a preliminary run with LENIZ and LENZ set to 1. (H02CEF will then terminate with IFAIL=14.)
31:   MONIT – SUBROUTINE, supplied by the NAG Library or the user.External Procedure
To provide feed-back on the progress of the branch and bound process. Additionally MONIT provides, via its argument HALT, the ability to terminate the process. (You might choose to do this when an integer solution is found, rather than search for a better solution.) If you do not require any intermediate output then MONIT may be the dummy routine H02CEY.
The specification of MONIT is:
SUBROUTINE MONIT ( INTFND, NODES, DEPTH, OBJ, X, BSTVAL, BSTSOL, BL, BU, N, HALT, COUNT)
INTEGER | INTFND, NODES, DEPTH, N, COUNT
REAL (KIND=nag_wp) | OBJ, X(N), BSTVAL, BSTSOL(N), BL(N), BU(N)
LOGICAL | HALT
1:   INTFND – INTEGERInput
On entry: contains the number of integer solutions obtained so far.
2:   NODES – INTEGERInput
On entry: contains the number of nodes (sub-problems) solved so far.
3:   DEPTH – INTEGERInput
On entry: contains the depth reached in the tree of problems.
4:   OBJ – REAL (KIND=nag_wp)Input
On entry: contains the solution value to the sub-problem at this node.
5:   X N – REAL (KIND=nag_wp) arrayInput
On entry: contains the solution vector to the sub-problem at this node.
6:   BSTVAL – REAL (KIND=nag_wp)Input/Output
On entry: contains the value of the objective function corresponding to the best integer solution obtained so far. If no integer solution has been found BSTVAL contains the largest machine representable number (see X02ALF).
On exit: may be set to a cut-off value, if you are a sophisticated user, as follows. Before an integer solution has been found BSTVAL will be set by H02CEF to the largest machine representable number (see X02ALF). If you know that the solution being sought is a much smaller number, then BSTVAL may be set to this number as a cut-off value (see Section 3). Beware of setting BSTVAL too small, since then no integer solutions will be discovered. Also make sure that BSTVAL is set using a statement of the form
IF (INTFND.EQ.0) BSTVAL= cut-off value
on entry to MONIT. This statement will not prevent the normal operation of the algorithm when subsequent integer solutions are found. It would be a grievous mistake to unconditionally set BSTVAL and if you have any doubts whatsoever about the correct use of this argument then you are strongly recommended to leave it unchanged.
7:   BSTSOL N – REAL (KIND=nag_wp) arrayInput
On entry: contains the value of the best integer solution obtained so far.
8:   BL N – REAL (KIND=nag_wp) arrayInput
On entry: contains the current lower bounds on the variables at this point.
9:   BU N – REAL (KIND=nag_wp) arrayInput
On entry: contains the current upper bounds on the variables at this point.
10:   N – INTEGERInput
On entry: contains the number of variables in the minimization problem.
11:   HALT – LOGICALInput/Output
On entry: will have the value .FALSE..
On exit: if HALT is set to .TRUE., E04NKF/E04NKA will be brought to a halt with IFAIL exit -1. This facility may be useful if you are content with any integer solution, or with any integer solution that fits certain criteria. Under these circumstances setting HALT=.TRUE. can save considerable unnecessary computation.
12:   COUNT – INTEGERUser Data
COUNT may be used to save the last value of INTFND. If a subsequent call of MONIT has a value of INTFND which is greater than COUNT, then you know that a new integer solution has been found at this node.
MONIT must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which H02CEF is called. Arguments denoted as Input must not be changed by this procedure.
32:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=-1
Halted at your request.
IFAIL=0
Successful exit.
IFAIL=1
Input argument error immediately detected.
IFAIL=2
No integer solution found.
IFAIL=3
MDEPTH is too small.
IFAIL=4
The problem is unbounded (or badly scaled). The objective function is not bounded below in the feasible region.
IFAIL=5
The problem is infeasible. The general constraints cannot all be satisfied simultaneously to within the value of the optional parameter Feasibility Tolerance (default value=max 10-6,ε, where ε is the machine precision).
IFAIL=6
Too many iterations. The value of the optional parameter Iteration Limit (default value=max 50,5 n+m) is too small.
IFAIL=7
The reduced Hessian matrix ZT HZ (see Section 11.2) exceeds its assigned dimension. The value of the optional parameter Superbasics Limit (default value=min nH+1,n) is too small.
IFAIL=8
The Hessian matrix H appears to be indefinite. Check that QPHX has been coded correctly and that all relevant elements of Hx have been assigned their correct values.
IFAIL=9
An input argument is invalid for an internal call to E04NKF/E04NKA.
IFAIL=10
Numerical error in trying to satisfy the general constraints. The basis is very ill-conditioned.
IFAIL=11
Not enough integer workspace for the basis factors. Increase LENIZ and rerun H02CEF.
IFAIL=12
Not enough real workspace for the basis factors. Increase LENZ and rerun H02CEF.
IFAIL=13
The basis is singular after 15 attempts to factorize it (adding slacks where necessary). Either the problem is badly scaled or the value of the optional parameter LU Factor Tolerance (default value=100.0) is too large.
IFAIL=14
Not enough integer workspace to start solving the problem. Increase LENIZ to at least MINIZ and rerun H02CEF.
IFAIL=15
Not enough real workspace to start solving the problem. Increase LENZ to at least MINZ and rerun H02CEF.
IFAIL=16
An internal error has occurred. Contact NAG with details of your program.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

H02CEF implements a numerically stable active-set strategy and returns solutions that are as accurate as the condition of the problem warrants on the machine.

8 Parallelism and Performance

H02CEF is not thread safe and should not be called from a multithreaded user program. Please see Section 3.12.1 in How to Use the NAG Library and its Documentation for more information on thread safety.
H02CEF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
H02CEF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

This section contains a description of the printed output.

9.1 Description of the Printed Output

This section describes the (default) intermediate printout and final printout produced by H02CEF. The intermediate printout is a subset of the monitoring information produced by the routine at every iteration (see Section 13). You can control the level of printed output (see the description of the optional parameter Print Level in Section 12.1). Note that the intermediate printout and final printout are produced only if Print Level≥10 (the default).
The following line of summary output (<80 characters) is produced at every iteration. In all cases, the values of the quantities printed are those in effect on completion of the given iteration.
Itn | is the iteration count.
Step | is the step taken along the computed search direction. If a constraint is added during the current iteration, Step will be the step to the nearest constraint. When the problem is of type LP, the step can be greater than one during the optimality phase.
Ninf | is the number of violated constraints (infeasibilities). This will be zero during the optimality phase.
Sinf/Objective | is the value of the current objective function. If x is not feasible, Sinf gives a weighted sum of the magnitudes of constraint violations. If x is feasible, Objective is the value of the objective function. The output line for the final iteration of the feasibility phase (i.e., the first iteration for which Ninf is zero) will give the value of the true objective at the first feasible point. During the optimality phase, the value of the objective function will be nonincreasing. During the feasibility phase, the number of constraint infeasibilities will not increase until either a feasible point is found, or the optimality of the multipliers implies that no feasible point exists. Once optimal multipliers are obtained, the number of infeasibilities can increase, but the sum of infeasibilities will either remain constant or be reduced until the minimum sum of infeasibilities is found.
Norm rg | is dS, the Euclidean norm of the reduced gradient (see Section 11.3). During the optimality phase, this norm will be approximately zero after a unit step. For FP and LP problems, Norm rg is not printed.
The final printout includes a listing of the status of every variable and constraint.
The following describes the printout for each variable. A full stop (.) is printed for any numerical value that is zero.
Variable | gives the name of the variable. If NNAME=1, a default name is assigned to the jth variable, for j=1,2,…,n. If NNAME=N+M, the name supplied in CRNAME j is assigned to the jth variable.
State gives the state of the variable (LL if nonbasic on its lower bound, UL if nonbasic on its upper bound, EQ if nonbasic and fixed, FR if nonbasic and strictly between its bounds, BS if basic and SBS if superbasic).
A key is sometimes printed before State to give some additional information about the state of a variable. Note that unless the optional parameter Scale Option=0 (default value=2) is specified, the tests for assigning a key are applied to the variables of the scaled problem.
A | Alternative optimum possible. The variable is nonbasic, but its reduced gradient is essentially zero. This means that if the variable were allowed to start moving away from its bound, there would be no change to the objective function. The values of the other free variables might change, giving a genuine alternative solution. However, if there are any degenerate variables (labelled D), the actual change might prove to be zero, since one of them could encounter a bound immediately. In either case the values of the Lagrange-multipliers might also change.
D | Degenerate. The variable is basic or superbasic, but it is equal to (or very close to) one of its bounds.
I | Infeasible. The variable is basic or superbasic and is currently violating one of its bounds by more than the value of the optional parameter Feasibility Tolerance (default value=max 10-6,ε, where ε is the machine precision).
N | Not precisely optimal. The variable is nonbasic or superbasic. If the value of the reduced gradient for the variable exceeds the value of the optional parameter Optimality Tolerance (default value=max 10-6,ε), the solution would not be declared optimal because the reduced gradient for the variable would not be considered negligible.
Value | is the value of the variable at the final iterate.
Lower Bound | is the lower bound specified for the variable. None indicates that BL j≤-bigbnd.
Upper Bound | is the upper bound specified for the variable. None indicates that BU j≥bigbnd.
Lagr Mult | is the Lagrange-multiplier for the associated bound. This will be zero if State is FR. If x is optimal, the multiplier should be non-negative if State is LL, non-positive if State is UL, and zero if State is BS or SBS.
Residual | is the difference between the variable Value and the nearer of its (finite) bounds BL j and BU j. A blank entry indicates that the associated variable is not bounded (i.e., BL j≤-bigbnd and BU j≥bigbnd).
The meaning of the printout for linear constraints is the same as that given above for variables, with ‘variable’ replaced by ‘constraint’, n replaced by m, CRNAME j replaced by CRNAME n+j, BL j and BU j are replaced by BL n+j and BU n+j respectively, and with the following change in the heading.
Constrnt gives the name of the linear constraint.
Note that movement off a constraint (as opposed to a variable moving away from its bound) can be interpreted as allowing the entry in the Residual column to become positive.
Numerical values are output with a fixed number of digits; they are not guaranteed to be accurate to this precision.

10 Example

This example minimizes the quadratic function f x=cT x+12 xT Hx, where
c=-200.0,-2000.0,-2000.0,-2000.0,-2000.0,400.0,400.0 T
H= 2 0 0 0 0 0 0 0 2 0 0 0 0 0 0 0 2 2 0 0 0 0 0 2 2 0 0 0 0 0 0 0 2 0 0 0 0 0 0 0 2 2 0 0 0 0 0 2 2
subject to the bounds
00 0≤x 1≤0 200 00 0≤x 2≤2500 400≤x 3≤0 800 100≤x 4≤0 700 00 0≤x 5≤1500 00 0≤x 6 00 0≤x 7
to the linear constraints
x 1 + x 2 + x 3 + x 4 + x 5 + x 6 + x 7 = 2000 0.15 x 1 + 0.04 x 2 + 0.02 x 3 + 0.04 x 4 + 0.02 x 5 + 0.01 x 6 + 0.03 x 7 ≤ 60 0.03 x 1 + 0.05 x 2 + 0.08 x 3 + 0.02 x 4 + 0.06 x 5 + 0.01 x 6 ≤ 100 0.02 x 1 + 0.04 x 2 + 0.01 x 3 + 0.02 x 4 + 0.02 x 5 ≤ 40 0.02 x 1 + 0.03 x 2 + 0.01 x 5 ≤ 30 1500 ≤ 0.70 x 1 + 0.75 x 2 + 0.80 x 3 + 0.75 x 4 + 0.80 x 5 + 0.97 x 6 250 ≤ 0.02 x 1 + 0.06 x 2 + 0.08 x 3 + 0.12 x 4 + 0.02 x 5 + 0.01 x 6 + 0.97 x 7 ≤ 300
and the variables x 2, x 3, x 4, x 5, x 6, x 7, are constrained to be integer.
The initial point, which is infeasible, is
x 0=0.0,0.0,0.0,0.0,0.0,0.0,0.0 T.
The optimal solution (to five figures) is
x*=0.0,355.0,645.0,164.0,410.0,275.0,151.0 T.
One bound constraint and one linear constraint are active at the solution. Note that the Hessian matrix H is positive semidefinite.

10.1 Program Text

Program Text (h02cefe.f90)

10.2 Program Data

Program Data (h02cefe.d)

10.3 Program Results

Program Results (h02cefe.r)

Note: the remainder of this document is intended for more advanced users. Section 11 contains a detailed description of the algorithm which may be needed in order to understand Sections 12 and 13. Section 12 describes the optional parameters which may be set by calls to H02CFF and/or H02CGF. Section 13 describes the quantities which can be requested to monitor the course of the computation.

11 Algorithmic Details

This section contains a detailed description of the method used by H02CEF.

11.1 Overview

H02CEF employs a Branch and Bound technique (see Section 3) based on an inertia-controlling method to solve the sub-problems that maintains a Cholesky factorization of the reduced Hessian (see below). The method is similar to that of Gill and Murray (1978), and is described in detail by Gill et al. (1991). Here we briefly summarise the main features of the method. Where possible, explicit reference is made to the names of variables that are arguments of the routine or appear in the printed output.
The method used has two distinct phases: finding an initial feasible point by minimizing the sum of infeasibilities (the feasibility phase), and minimizing the quadratic objective function within the feasible region (the optimality phase). The computations in both phases are performed by the same subroutines. The two-phase nature of the algorithm is reflected by changing the function being minimized from the sum of infeasibilities (the printed quantity Sinf; see Section 13) to the quadratic objective function (the printed quantity Objective; see Section 13).
In general, an iterative process is required to solve a quadratic program. Given an iterate x,s in both the original variables x and the slack variables s, a new iterate x-,s- is defined by
x- s- = x s +αp, (2)
where the step length α is a non-negative scalar (the printed quantity Step; see Section 13), and p is called the search direction. (For simplicity, we shall consider a typical iteration and avoid reference to the index of the iteration.) Once an iterate is feasible (i.e., satisfies the constraints), all subsequent iterates remain feasible.

11.2 Definition of the Working Set and Search Direction

At each iterate x,s, a working set of constraints is defined to be a linearly independent subset of the constraints that are satisfied ‘exactly’ (to within the value of the optional parameter Feasibility Tolerance; see Section 12.1). The working set is the current prediction of the constraints that hold with equality at a solution of the LP or QP problem. Let mW denote the number of constraints in the working set (including bounds), and let W denote the associated mW by n+m working set matrix consisting of the mW gradients of the working set constraints.
The search direction is defined so that constraints in the working set remain unaltered for any value of the step length. It follows that p must satisfy the identity
Wp=0. (3)
This characterisation allows p to be computed using any n by nZ full-rank matrix Z that spans the null space of W. (Thus, nZ=n-mW and WZ=0.) The null space matrix Z is defined from a sparse LU factorization of part of W (see (6) and (7) below). The direction p will satisfy (3) if
p=Z pZ, (4)
where pZ is any nZ-vector.
The working set contains the constraints Ax-s=0 and a subset of the upper and lower bounds on the variables x,s. Since the gradient of a bound constraint xj≥lj or xj≤uj is a vector of all zeros except for ±1 in position j, it follows that the working set matrix contains the rows of A-I and the unit rows associated with the upper and lower bounds in the working set.
The working set matrix W can be represented in terms of a certain column partition of the matrix A-I. As in Section 3 we partition the constraints Ax-s=0 so that
B xB+S xS+N xN=0, (5)
where B is a square nonsingular basis and xB, xS and xN are the basic, superbasic and nonbasic variables respectively. The nonbasic variables are equal to their upper or lower bounds at x,s, and the superbasic variables are independent variables that are chosen to improve the value of the current objective function. The number of superbasic variables is nS (the printed quantity Ns; see Section 13). Given values of xN and xS, the basic variables xB are adjusted so that x,s satisfies (5).
If P is a permutation matrix such that A-I P=B S N, then the working set matrix W satisfies
WP= B S N 0 0 IN , (6)
where IN is the identity matrix with the same number of columns as N.
The null space matrix Z is defined from a sparse LU factorization of part of W. In particular, Z is maintained in ‘reduced gradient’ form, using the LUSOL package (see Gill et al. (1986)) to maintain sparse LU factors of the basis matrix B that alters as the working set W changes. Given the permutation P, the null space basis is given by
Z=P -B-1 S I 0 . (7)
This matrix is used only as an operator, i.e., it is never computed explicitly. Products of the form Zv and ZT g are obtained by solving with B or BT. This choice of Z implies that nZ, the number of ‘degrees of freedom’ at x,s, is the same as nS, the number of superbasic variables.
Let gZ and HZ denote the reduced gradient and reduced Hessian of the objective function:
gZ=ZT g  and  HZ=ZT HZ, (8)
where g is the objective gradient at x,s. Roughly speaking, gZ and HZ describe the first and second derivatives of an nS-dimensional unconstrained problem for the calculation of pZ. (The condition estimator of HZ is the quantity Cond Hz in the monitoring file output; see Section 13.)
At each iteration, an upper triangular factor R is available such that HZ=RT R. Normally, R is computed from RT R=ZT HZ at the start of the optimality phase and then updated as the QP working set changes. For efficiency, the dimension of R should not be excessive (say, nS≤1000). This is guaranteed if the number of nonlinear variables is ‘moderate’.
If the QP problem contains linear variables, H is positive semidefinite and R may be singular with at least one zero diagonal element. However, an inertia-controlling strategy is used to ensure that only the last diagonal element of R can be zero. (See Gill et al. (1991) for a discussion of a similar strategy for indefinite quadratic programming.)
If the initial R is singular, enough variables are fixed at their current value to give a nonsingular R. This is equivalent to including temporary bound constraints in the working set. Thereafter, R can become singular only when a constraint is deleted from the working set (in which case no further constraints are deleted until R becomes nonsingular).

11.3 The Main Iteration

If the reduced gradient is zero, x,s is a constrained stationary point on the working set. During the feasibility phase, the reduced gradient will usually be zero only at a vertex (although it may be zero elsewhere in the presence of constraint dependencies). During the optimality phase, a zero reduced gradient implies that x minimizes the quadratic objective function when the constraints in the working set are treated as equalities. At a constrained stationary point, Lagrange-multipliers λ are defined from the equations
WT λ=g x. (9)
A Lagrange-multiplier λj corresponding to an inequality constraint in the working set is said to be optimal if λj≤σ when the associated constraint is at its upper bound, or if λj≥-σ when the associated constraint is at its lower bound, where σ depends on the value of the optional parameter Optimality Tolerance (see Section 12.1). If a multiplier is nonoptimal, the objective function (either the true objective or the sum of infeasibilities) can be reduced by continuing the minimization with the corresponding constraint excluded from the working set. (This step is sometimes referred to as ‘deleting’ a constraint from the working set.) If optimal multipliers occur during the feasibility phase but the sum of infeasibilities is nonzero, there is no feasible point and the routine terminates immediately with IFAIL=3 (see Section 6).
The special form (6) of the working set allows the multiplier vector λ, the solution of (9), to be written in terms of the vector
d= g 0 - A -I T π= g-AT π π , (10)
where π satisfies the equations BT π=gB, and gB denotes the basic elements of g. The elements of π are the Lagrange-multipliers λj associated with the equality constraints Ax-s=0. The vector dN of nonbasic elements of d consists of the Lagrange-multipliers λj associated with the upper and lower bound constraints in the working set. The vector dS of superbasic elements of d is the reduced gradient gZ in (8). The vector dB of basic elements of d is zero, by construction. (The Euclidean norm of dS and the final values of dS, g and π are the quantities Norm rg, Reduced Gradnt, Obj Gradient and Dual Activity in the monitoring file output; see Section 13.)
If the reduced gradient is not zero, Lagrange-multipliers need not be computed and the search direction is given by p=Z pZ (see (7) and (11)). The step length is chosen to maintain feasibility with respect to the satisfied constraints.
There are two possible choices for pZ, depending on whether or not HZ is singular. If HZ is nonsingular, R is nonsingular and pZ in (4) is computed from the equations
RT R pZ=-gZ, (11)
where gZ is the reduced gradient at x. In this case, x,s+p is the minimizer of the objective function subject to the working set constraints being treated as equalities. If x,s+p is feasible, α is defined to be unity. In this case, the reduced gradient at x-,s- will be zero, and Lagrange-multipliers are computed at the next iteration. Otherwise, α is set to αM, the step to the ‘nearest’ constraint along p. This constraint is added to the working set at the next iteration.
If HZ is singular, then R must also be singular, and an inertia-controlling strategy is used to ensure that only the last diagonal element of R is zero. (See Gill et al. (1991) for a discussion of a similar strategy for indefinite quadratic programming.) In this case, pZ satisfies
pZT HZpZ=0  and   gZT pZ≤0, (12)
which allows the objective function to be reduced by any step of the form x,s+αp, where α>0. The vector p=Z pZ is a direction of unbounded descent for the QP problem in the sense that the QP objective is linear and decreases without bound along p. If no finite step of the form x,s+αp (where α>0) reaches a constraint not in the working set, the QP problem is unbounded and the routine terminates immediately with IFAIL=2 (see Section 6). Otherwise, α is defined as the maximum feasible step along p and a constraint active at x,s+αp is added to the working set for the next iteration.

11.4 Miscellaneous

If the basis matrix is not chosen carefully, the condition of the null space matrix Z in (7) could be arbitrarily high. To guard against this, the routine implements a ‘basis repair’ feature in which the LUSOL package (see Gill et al. (1986)) is used to compute the rectangular factorization
B S T=LU, (13)
returning just the permutation P that makes PL PT unit lower triangular. The pivot tolerance is set to require PL PT ij ≤2, and the permutation is used to define P in (6). It can be shown that Z is likely to be little more than unity. Hence, Z should be well-conditioned regardless of the condition of W. This feature is applied at the beginning of the optimality phase if a potential B-S ordering is known.
The EXPAND procedure (see Gill et al. (1989)) is used to reduce the possibility of cycling at a point where the active constraints are nearly linearly dependent. Although there is no absolute guarantee that cycling will not occur, the probability of cycling is extremely small (see Gill et al. (1986)). The main feature of EXPAND is that the feasibility tolerance is increased at the start of every iteration. This allows a positive step to be taken at every iteration, perhaps at the expense of violating the bounds on x,s by a small amount.
Suppose that the value of the optional parameter Feasibility Tolerance is δ. Over a period of K iterations (where K is the value of the optional parameter Expand Frequency; see Section 12.1), the feasibility tolerance actually used by H02CEF (i.e., the working feasibility tolerance) increases from 0.5 δ to δ (in steps of 0.5 δ/K).
At certain stages the following ‘resetting procedure’ is used to remove small constraint infeasibilities. First, all nonbasic variables are moved exactly onto their bounds. A count is kept of the number of nontrivial adjustments made. If the count is nonzero, the basic variables are recomputed. Finally, the working feasibility tolerance is reinitialized to 0.5 δ.
If a problem requires more than K iterations, the resetting procedure is invoked and a new cycle of iterations is started. (The decision to resume the feasibility phase or optimality phase is based on comparing any constraint infeasibilities with δ.)
The resetting procedure is also invoked when H02CEF reaches an apparently optimal, infeasible or unbounded solution, unless this situation has already occurred twice. If any nontrivial adjustments are made, iterations are continued.
The EXPAND procedure not only allows a positive step to be taken at every iteration, but also provides a potential choice of constraints to be added to the working set. All constraints at a distance α (where α≤αM) along p from the current point are then viewed as acceptable candidates for inclusion in the working set. The constraint whose normal makes the largest angle with the search direction is added to the working set. This strategy helps keep the basis matrix B well-conditioned.

12 Optional Parameters

Several optional parameters in H02CEF define choices in the problem specification or the algorithm logic. In order to reduce the number of formal arguments of H02CEF these optional parameters have associated default values that are appropriate for most problems. Therefore, you need only specify those optional parameters whose values are to be different from their default values.
The remainder of this section can be skipped if you wish to use the default values for all optional parameters.
The following is a list of the optional parameters available. A full description of each optional parameter is provided in Section 12.1.
  • Check Frequency
  • Crash Option
  • Crash Tolerance
  • Defaults
  • Expand Frequency
  • Factorization Frequency
  • Feasibility Tolerance
  • Infinite Bound Size
  • Infinite Step Size
  • Iteration Limit
  • Iters
  • Itns
  • List
  • LU Factor Tolerance
  • LU Singularity Tolerance
  • LU Update Tolerance
  • Maximize
  • Minimize
  • Monitoring File
  • Nolist
  • Optimality Tolerance
  • Partial Price
  • Pivot Tolerance
  • Print Level
  • Rank Tolerance
  • Scale Option
  • Scale Tolerance
  • Superbasics Limit
Optional parameters may be specified by calling one, or both, of the routines H02CFF and H02CGF prior to a call to H02CEF.
H02CFF reads options from an external options file, with Begin and End as the first and last lines respectively and each intermediate line defining a single optional parameter. For example,
Begin
Print Level = 5
End
The call
CALL H02CFF(IOPTNS,INFORM)
can then be used to read the file on unit IOPTNS. INFORM will be zero on successful exit. H02CFF should be consulted for a full description of this method of supplying optional parameters.
H02CGF can be called to supply options directly, one call being necessary for each optional parameter. For example,
CALL H02CGF ('Print Level = 5')
H02CGF should be consulted for a full description of this method of supplying optional parameters.
All optional parameters not specified by you are set to their default values. Optional parameters specified by you are unaltered by H02CEF (unless they define invalid values) and so remain in effect for subsequent calls unless altered by you.

12.1 Description of the Optional Parameters

For each option, we give a summary line, a description of the optional parameter and details of constraints.
The summary line contains:
  • the keywords, where the minimum abbreviation of each keyword is underlined (if no characters of an optional qualifier are underlined, the qualifier may be omitted);
  • a parameter value, where the letters a, i and r denote options that take character, integer and real values respectively;
  • the default value is used whenever the condition i≥100000000 is satisfied and where the symbol ε is a generic notation for machine precision (see X02AJF).
Keywords and character values are case and white space insensitive.
Check Frequency i Default =60
Every ith iteration after the most recent basis factorization, a numerical test is made to see if the current solution x,s satisfies the linear constraints Ax-s=0. If the largest element of the residual vector r=Ax-s is judged to be too large, the current basis is refactorized and the basic variables recomputed to satisfy the constraints more accurately. If i<0, the default value is used. If i=0, the value i=99999999 is used and effectively no checks are made.
Crash Option i Default =2
Note that this option does not apply when START='W' (see Section 5).
If START='C', an internal crash procedure is used to select an initial basis from various rows and columns of the constraint matrix A-I. The value of i determines which rows and columns are initially eligible for the basis, and how many times the crash procedure is called. If i=0, the all-slack basis B=-I is chosen. If i=1, the crash procedure is called once (looking for a triangular basis in all rows and columns of the linear constraint matrix A). If i=2, the crash procedure is called twice (looking at any equality constraints first followed by any inequality constraints). If i<0 or i>2, the default value is used.
If i=1​ or ​2, certain slacks on inequality rows are selected for the basis first. (If i=2, numerical values are used to exclude slacks that are close to a bound.) The crash procedure then makes several passes through the columns of A, searching for a basis matrix that is essentially triangular. A column is assigned to ‘pivot’ on a particular row if the column contains a suitably large element in a row that has not yet been assigned. (The pivot elements ultimately form the diagonals of the triangular basis.) For remaining unassigned rows, slack variables are inserted to complete the basis.
Crash Tolerance r Default =0.1
This value allows the crash procedure to ignore certain ‘small’ nonzero elements in the constraint matrix A while searching for a triangular basis. For each column of A, if amax is the largest element in the column, other nonzeros in that column are ignored if they are less than (or equal to) amax×r.
When r>0, the basis obtained by the crash procedure may not be strictly triangular, but it is likely to be nonsingular and almost triangular. The intention is to obtain a starting basis with more column variables and fewer (arbitrary) slacks. A feasible solution may be reached earlier for some problems. If r<0 or r≥1, the default value is used.
Defaults
This special keyword may be used to reset all optional parameters to their default values.
Expand Frequency i Default =10000
This option is part of an anti-cycling procedure (see Section 11.4) designed to allow progress even on highly degenerate problems.
For LP problems, the strategy is to force a positive step at every iteration, at the expense of violating the constraints by a small amount. Suppose that the value of the optional parameter Feasibility Tolerance is δ. Over a period of i iterations, the feasibility tolerance actually used by H02CEF (i.e., the working feasibility tolerance) increases from 0.5 δ to δ (in steps of 0.5 δ/i).
For QP problems, the same procedure is used for iterations in which there is only one superbasic variable. (Cycling can only occur when the current solution is at a vertex of the feasible region.) Thus, zero steps are allowed if there is more than one superbasic variable, but otherwise positive steps are enforced.
Increasing the value of i helps reduce the number of slightly infeasible nonbasic basic variables (most of which are eliminated during the resetting procedure). However, it also diminishes the freedom to choose a large pivot element (see the description of the optional parameter Pivot Tolerance).
If i<0, the default value is used. If i=0, the value i=99999999 is used and effectively no anti-cycling procedure is invoked.
Factorization Frequency i Default =100
If i>0, at most i basis changes will occur between factorizations of the basis matrix. For LP problems, the basis factors are usually updated at every iteration. For QP problems, fewer basis updates will occur as the solution is approached. The number of iterations between basis factorizations will therefore increase. During these iterations a test is made regularly according to the value of optional parameter Check Frequency to ensure that the linear constraints Ax-s=0 are satisfied. If necessary, the basis will be refactorized before the limit of i updates is reached. If i≤0, the default value is used.
Feasibility Tolerance r Default =max 10-6,ε
If r≥ε, r defines the maximum acceptable absolute violation in each constraint at a ‘feasible’ point (including slack variables). For example, if the variables and the coefficients in the linear constraints are of order unity, and the latter are correct to about five decimal digits, it would be appropriate to specify r as 10-5. If r<ε, the default value is used.
H02CEF attempts to find a feasible solution before optimizing the objective function. If the sum of infeasibilities cannot be reduced to zero, the problem is assumed to be infeasible. Let Sinf be the corresponding sum of infeasibilities. If Sinf is quite small, it may be appropriate to raise r by a factor of 10 or 100. Otherwise, some error in the data should be suspected. Note that the routine does not attempt to find the minimum value of Sinf.
If the constraints and variables have been scaled (see the description of the optional parameter Scale Option), then feasibility is defined in terms of the scaled problem (since it is more likely to be meaningful).
Infinite Bound Size r Default =1020
If r>0, r defines the ‘infinite’ bound bigbnd in the definition of the problem constraints. Any upper bound greater than or equal to bigbnd will be regarded as +∞ (and similarly any lower bound less than or equal to -bigbnd will be regarded as -∞). If r≤0, the default value is used.
Infinite Step Size r Default =max bigbnd,1020
If r>0, r specifies the magnitude of the change in variables that will be considered a step to an unbounded solution. (Note that an unbounded solution can occur only when the Hessian is not positive definite.) If the change in x during an iteration would exceed the value of r, the objective function is considered to be unbounded below in the feasible region. If r≤0, the default value is used.
Iteration Limit i Default =max 50,5 n+m
Iters
Itns
The value of i specifies the maximum number of iterations allowed before termination. Setting i=0 and Print Level>0 means that the workspace needed to start solving the problem will be computed and printed, but no iterations will be performed. If i<0, the default value is used.
List Default
Nolist
Normally each optional parameter specification is printed as it is supplied. Optional parameter Nolist may be used to suppress the printing and optional parameter List may be used to restore printing.
LU Factor Tolerance r 1 Default =100.0
LU Update Tolerance r 2 Default =10.0
The values of r 1 and r 2 affect the stability and sparsity of the basis factorization B=LU, during refactorization and updates respectively. The lower triangular matrix L is a product of matrices of the form
1 0 μ 1
where the multipliers μ will satisfy μ≤ri. The default values of r 1 and r 2 usually strike a good compromise between stability and sparsity. For large and relatively dense problems, setting r 1 and r 2 to 25 (say) may give a marked improvement in sparsity without impairing stability to a serious degree. Note that for band matrices it may be necessary to set r 1 in the range 1≤r 1<2 in order to achieve stability. If r 1<1 or r 2<1, the default value is used.
LU Singularity Tolerance r Default =ε 0.67
If r>0, r defines the singularity tolerance used to guard against ill-conditioned basis matrices. Whenever the basis is refactorized, the diagonal elements of U are tested as follows. If u jj≤r or u jj<r×maxi u ij, the jth column of the basis is replaced by the corresponding slack variable. If r≤0, the default value is used.
Minimize Default
Maximize
This option specifies the required direction of the optimization. It applies to both linear and nonlinear terms (if any) in the objective function. Note that if two problems are the same except that one minimizes f x and the other maximizes -f x, their solutions will be the same but the signs of the dual variables πi and the reduced gradients dj (see Section 11.3) will be reversed.
Monitoring File i Default =-1
If i≥0 and Print Level>0, monitoring information produced by H02CEF is sent to a file with logical unit number i. If i<0 and/or Print Level=0, the default value is used and hence no monitoring information is produced.
Optimality Tolerance r Default =max 10-6,ε
If r≥ε, r is used to judge the size of the reduced gradients dj=gj-πT aj. By definition, the reduced gradients for basic variables are always zero. Optimality is declared if the reduced gradients for any nonbasic variables at their lower or upper bounds satisfy -r×max 1,π≤dj≤r×max 1,π, and if dj≤r×max 1,π for any superbasic variables. If r<ε, the default value is used.
Partial Price i Default =10
Note that this option does not apply to QP problems.
This option is recommended for large FP or LP problems that have significantly more variables than constraints (i.e., n≫m). It reduces the work required for each pricing operation (i.e., when a nonbasic variable is selected to enter the basis). If i=1, all columns of the constraint matrix A-I are searched. If i>1, A and -I are partitioned to give i roughly equal segments Aj,Kj, for j=1,2,…,p (modulo p). If the previous pricing search was successful on A j-1,K j-1, the next search begins on the segments Aj,Kj. If a reduced gradient is found that is larger than some dynamic tolerance, the variable with the largest such reduced gradient (of appropriate sign) is selected to enter the basis. If nothing is found, the search continues on the next segments A j+1,K j+1, and so on. If i≤0, the default value is used.
Pivot Tolerance r Default =ε 0.67
If r>0, r is used to prevent columns entering the basis if they would cause the basis to become almost singular. If r≤0, the default value is used.
Print Level i Default =10
The value of i controls the amount of printout produced by H02CEF, as indicated below. A detailed description of the printed output is given in Section 9.1 (summary output at each iteration and the final solution) and Section 13 (monitoring information at each iteration). Note that the summary output will not exceed 80 characters per line and that the monitoring information will not exceed 120 characters per line. If i<0, the default value is used. The following printout is sent to the current advisory message unit (as defined by X04ABF):
≥0 i | Output
≥0 0 | No output.
≥0 1 | The final solution only.
≥0 5 | One line of summary output for each iteration (no printout of the final solution).
≥10 | The final solution and one line of summary output for each iteration.
The following printout is sent to the logical unit number defined by the Monitoring File:
≥0 i | Output
≥0 0 | No output.
≥0 1 | The final solution only.
≥0 5 | One long line of output for each iteration (no printout of the final solution).
≥10 | The final solution and one long line of output for each iteration.
≥20 | The final solution, one long line of output for each iteration, matrix statistics (initial status of rows and columns, number of elements, density, biggest and smallest elements, etc.), details of the scale factors resulting from the scaling procedure (if Scale Option=1 or 2), basis factorization statistics and details of the initial basis resulting from the crash procedure (if START='C'; see Section 5).
If Print Level>0 and the unit number defined by Monitoring File is the same as that defined by X04ABF, then the summary output is suppressed.
Rank Tolerance r Default =100 ε
Scale Option i Default =2
This option enables you to scale the variables and constraints using an iterative procedure due to Fourer (see Hock and Schittkowski (1981)), which attempts to compute row scales ri and column scales cj such that the scaled matrix coefficients a-ij=a ij×cj/ri are as close as possible to unity. This may improve the overall efficiency of the routine on some problems. (The lower and upper bounds on the variables and slacks for the scaled problem are redefined as l-j=lj/cj and u-j=uj/cj respectively, where cj≡r j-n if j>n.)
If i=0, no scaling is performed. If i=1, all rows and columns of the constraint matrix A are scaled. If i=2, an additional scaling is performed that may be helpful when the solution x is large; it takes into account columns of A-I that are fixed or have positive lower bounds or negative upper bounds. If i<0 or i>2, the default value is used.
Scale Tolerance r Default =0.9
Note that this option does not apply when Scale Option=0.
If 0<r<1, r is used to control the number of scaling passes to be made through the constraint matrix A. At least 3 (and at most 10) passes will be made. More precisely, let ap denote the largest column ratio (i.e., 'biggest'element 'smallest'element in some sense) after the pth scaling pass through A. The scaling procedure is terminated if ap≥a p-1×r for some p≥3. Thus, increasing the value of r from 0.9 to 0.99 (say) will probably increase the number of passes through A. If r≤0 or r≥1, the default value is used.
Superbasics Limit i Default =min nH+1,n
Note that this option does not apply to FP or LP problems.
The value of i specifies ‘how nonlinear’ you expect the QP problem to be. If i≤0, the default value is used.

13 Description of Monitoring Information

This section describes the intermediate printout and final printout which constitutes the monitoring information produced by H02CEF. (See also the description of the optional parameters Monitoring File and Print Level in Section 12.1.) You can control the level of printed output.
When Print Level=5 or ≥10 and Monitoring File≥0, the following line of intermediate printout (<120 characters) is produced at every iteration on the unit number specified by Monitoring File. Unless stated otherwise, the values of the quantities printed are those in effect on completion of the given iteration.
Itn | is the iteration count.
pp | is the partial price indicator. The variable selected by the last pricing operation came from the ppth partition of A and -I. Note that pp is reset to zero whenever the basis is refactorized.
dj | is the value of the reduced gradient (or reduced cost) for the variable selected by the pricing operation at the start of the current iteration.
+S | is the variable selected by the pricing operation to be added to the superbasic set.
-S | is the variable chosen to leave the superbasic set.
-B | is the variable removed from the basis (if any) to become nonbasic.
-B | is the variable chosen to leave the set of basics (if any) in a special basic ↔ superbasic swap. The entry under -S has become basic if this entry is nonzero, and nonbasic otherwise. The swap is done to ensure that there are no superbasic slacks.
Step | is the value of the step length α taken along the computed search direction p. The variables x have been changed to x+αp. If a variable is made superbasic during the current iteration (i.e., +S is positive), Step will be the step to the nearest bound. During the optimality phase, the step can be greater than unity only if the reduced Hessian is not positive definite.
Pivot | is the rth element of a vector y satisfying By=aq whenever aq (the qth column of the constraint matrix A-I) replaces the rth column of the basis matrix B. Wherever possible, Step is chosen so as to avoid extremely small values of Pivot (since they may cause the basis to be nearly singular). In extreme cases, it may be necessary to increase the value of the optional parameter Pivot Tolerance (default value=ε 0.67, where ε is the machine precision) to exclude very small elements of y from consideration during the computation of Step.
Ninf | is the number of violated constraints (infeasibilities). This will be zero during the optimality phase.
Sinf/Objective | is the value of the current objective function. If x is not feasible, Sinf gives a weighted sum of the magnitudes of constraint violations. If x is feasible, Objective is the value of the objective function. The output line for the final iteration of the feasibility phase (i.e., the first iteration for which Ninf is zero) will give the value of the true objective at the first feasible point. During the optimality phase, the value of the objective function will be nonincreasing. During the feasibility phase, the number of constraint infeasibilities will not increase until either a feasible point is found, or the optimality of the multipliers implies that no feasible point exists. Once optimal multipliers are obtained, the number of infeasibilities can increase, but the sum of infeasibilities will either remain constant or be reduced until the minimum sum of infeasibilities is found.
L | is the number of nonzeros in the basis factor L. Immediately after a basis factorization B=LU, this is lenL, the number of subdiagonal elements in the columns of a lower triangular matrix. Further nonzeros are added to L when various columns of B are later replaced. (Thus, L increases monotonically.)
U | is the number of nonzeros in the basis factor U. Immediately after a basis factorization, this is lenU, the number of diagonal and superdiagonal elements in the rows of an upper triangular matrix. As columns of B are replaced, the matrix U is maintained explicitly (in sparse form). The value of U may fluctuate up or down; in general, it will tend to increase.
Ncp | is the number of compressions required to recover workspace in the data structure for U. This includes the number of compressions needed during the previous basis factorization. Normally, Ncp should increase very slowly. If it does not, increase LENZ by at least L+U and rerun H02CEF (possibly using START='W'; see Section 5).
Norm rg | is dS, the Euclidean norm of the reduced gradient (see Section 11.3). During the optimality phase, this norm will be approximately zero after a unit step. For FP and LP problems, Norm rg is not printed.
Ns | is the current number of superbasic variables. For FP and LP problems, Ns is not printed.
Cond Hz | is a lower bound on the condition number of the reduced Hessian (see Section 11.2). The larger this number, the more difficult the problem. For FP and LP problems, Cond Hz is not printed.
When Print Level≥20 and Monitoring File≥0, the following lines of intermediate printout (<120 characters) are produced on the unit number specified by Monitoring File whenever the matrix B or BS= B S T is factorized. Gaussian elimination is used to compute an LU factorization of B or BS, where PL PT is a lower triangular matrix and PUQ is an upper triangular matrix for some permutation matrices P and Q. The factorization is stabilized in the manner described under the LU Factor Tolerance (default value=100.0; see Section 12.1).
Factorize | is the factorization count.
Demand is a code giving the reason for the present factorization as follows:
Code | Meaning
01 0 | First LU factorization.
01 1 | Number of updates reached the value of the optional parameter Factorization Frequency (default value=100).
01 2 | Excessive nonzeros in updated factors.
01 7 | Not enough storage to update factors.
0 10 | Row residuals too large (see the description for the optional parameter Check Frequency).
0 11 | Ill-conditioning has caused inconsistent results.
Iteration | is the iteration count.
Nonlinear | is the number of nonlinear variables in B (not printed if BS is factorized).
Linear | is the number of linear variables in B (not printed if BS is factorized).
Slacks | is the number of slack variables in B (not printed if BS is factorized).
Elems | is the number of nonzeros in B (not printed if BS is factorized).
Density | is the percentage nonzero density of B (not printed if BS is factorized). More precisely, Density=100×Elems/Nonlinear+Linear+Slacks 2.
Compressns | is the number of times the data structure holding the partially factorized matrix needed to be compressed, in order to recover unused workspace. Ideally, it should be zero. If it is more than 3 or 4, increase LENIZ and LENZ and rerun H02CEF (possibly using START='W'; see Section 5).
Merit | is the average Markowitz merit count for the elements chosen to be the diagonals of PUQ. Each merit count is defined to be c-1r-1, where c and r are the number of nonzeros in the column and row containing the element at the time it is selected to be the next diagonal. Merit is the average of m such quantities. It gives an indication of how much work was required to preserve sparsity during the factorization.
lenL | is the number of nonzeros in L.
lenU | is the number of nonzeros in U.
Increase | is the percentage increase in the number of nonzeros in L and U relative to the number of nonzeros in B. More precisely, Increase=100×lenL+lenU-Elems/Elems.
m | is the number of rows in the problem. Note that m=Ut+Lt+bp.
Ut | is the number of triangular rows of B at the top of U.
d1 | is the number of columns remaining when the density of the basis matrix being factorized reached 0.3.
Lmax | is the maximum subdiagonal element in the columns of L (not printed if BS is factorized). This will not exceed the value of the LU Factor Tolerance.
Bmax | is the maximum nonzero element in B (not printed if BS is factorized).
BSmax | is the maximum nonzero element in BS (not printed if B is factorized).
Umax is the maximum nonzero element in U, excluding elements of B that remain in U unchanged. (For example, if a slack variable is in the basis, the corresponding row of B will become a row of U without modification. Elements in such rows will not contribute to Umax. If the basis is strictly triangular, none of the elements of B will contribute, and Umax will be zero.)
Ideally, Umax should not be significantly larger than Bmax. If it is several orders of magnitude larger, it may be advisable to reset the LU Factor Tolerance to a value near 1.0.
Umax is not printed if BS is factorized.
Umin | is the magnitude of the smallest diagonal element of PUQ (not printed if BS is factorized).
Growth is the value of the ratio Umax/Bmax, which should not be too large.
Providing Lmax is not large (say <10.0), the ratio max Bmax,Umax/Umin is an estimate of the condition number of B. If this number is extremely large, the basis is nearly singular and some numerical difficulties could occur in subsequent computations. (However, an effort is made to avoid near singularity by using slacks to replace columns of B that would have made Umin extremely small, and the modified basis is refactorized.)
Growth is not printed if BS is factorized.
Lt | is the number of triangular columns of B at the beginning of L.
bp | is the size of the ‘bump’ or block to be factorized nontrivially after the triangular rows and columns have been removed.
d2 | is the number of columns remaining when the density of the basis matrix being factorized reached 0.6.
When Print Level≥20 and Monitoring File≥0, the following lines of intermediate printout (<80 characters) are produced on the unit number specified by Monitoring File whenever START='C' (see Section 5). They refer to the number of columns selected by the crash procedure during each of several passes through A, whilst searching for a triangular basis matrix.
Slacks | is the number of slacks selected initially.
Free cols | is the number of free columns in the basis.
Preferred | is the number of ‘preferred’ columns in the basis (i.e., ISTATE j=3 for some j≤n).
Unit | is the number of unit columns in the basis.
Double | is the number of double columns in the basis.
Triangle | is the number of triangular columns in the basis.
Pad | is the number of slacks used to pad the basis.
When Print Level≥20 and Monitoring File≥0, the following lines of intermediate printout (<80 characters) are produced on the unit number specified by Monitoring File. They refer to the elements of the NAMES array (see Section 5).
Name | gives the name for the problem (blank if none).
Objective | gives the name of the free row for the problem (blank if none).
RHS | gives the name of the constraint right-hand side for the problem (blank if none).
Ranges | gives the name of the ranges for the problem (blank if none).
Bounds | gives the name of the bounds for the problem (blank if none).
When Print Level=1 or ≥10 and Monitoring File≥0, the following lines of final printout (<120 characters) are produced on the unit number specified by Monitoring File.
Let aj denote the jth column of A, for j=1,2,…,n. The following describes the printout for each column (or variable). A full stop (.) is printed for any numerical value that is zero.
Number | is the column number j. (This is used internally to refer to xj in the intermediate output.)
Column | gives the name of xj.
State gives the state of the variable (LL if nonbasic on its lower bound, UL if nonbasic on its upper bound, EQ if nonbasic and fixed, FR if nonbasic and strictly between its bounds, BS if basic and SBS if superbasic).
A key is sometimes printed before State to give some additional information about the state of xj. Note that unless the optional parameter Scale Option=0 (default value=2) is specified, the tests for assigning a key are applied to the variables of the scaled problem.
A | Alternative optimum possible. The variable is nonbasic, but its reduced gradient is essentially zero. This means that if the variable were allowed to start moving away from its bound, there would be no change to the objective function. The values of the other free variables might change, giving a genuine alternative solution. However, if there are any degenerate variables (labelled D), the actual change might prove to be zero, since one of them could encounter a bound immediately. In either case the values of the Lagrange-multipliers might also change.
D | Degenerate. The variable is basic or superbasic, but it is equal to (or very close to) one of its bounds.
I | Infeasible. The variable is basic or superbasic and is currently violating one of its bounds by more than the value of the optional parameter Feasibility Tolerance (default value=max 10-6,ε, where ε is the machine precision).
N | Not precisely optimal. The variable is nonbasic or superbasic. If the value of the reduced gradient for the variable exceeds the value of the optional parameter Optimality Tolerance (default value=max 10-6,ε), the solution would not be declared optimal because the reduced gradient for the variable would not be considered negligible.
Activity | is the value of xj at the final iterate.
Obj Gradient | is the value of gj at the final iterate. For FP problems, gj is set to zero.
Lower Bound | is the lower bound specified for the variable. None indicates that BL j≤-bigbnd.
Upper Bound | is the upper bound specified for the variable. None indicates that BU j≥bigbnd.
Reduced Gradnt | is the value of dj at the final iterate (see Section 11.3). For FP problems, dj is set to zero.
m + j | is the value of m+j.
Let vi denote the ith row of A, for i=1,2,…,m. The following describes the printout for each row (or constraint). A full stop (.) is printed for any numerical value that is zero.
Number | is the value of n+i. (This is used internally to refer to si in the intermediate output.)
Row | gives the name of νi.
State gives the state of the variable (LL if active on its lower bound, UL if active on its upper bound, EQ if active and fixed, BS if inactive when si is basic and SBS if inactive when si is superbasic).
A key is sometimes printed before State to give some additional information about the state of si. Note that unless the optional parameter Scale Option=0 (default value=2) is specified, the tests for assigning a key are applied to the variables of the scaled problem.
A | Alternative optimum possible. The variable is nonbasic, but its reduced gradient is essentially zero. This means that if the variable were allowed to start moving away from its bound, there would be no change to the objective function. The values of the other free variables might change, giving a genuine alternative solution. However, if there are any degenerate variables (labelled D), the actual change might prove to be zero, since one of them could encounter a bound immediately. In either case the values of the Lagrange-multipliers might also change.
D | Degenerate. The variable is basic or superbasic, but it is equal to (or very close to) one of its bounds.
I | Infeasible. The variable is basic or superbasic and is currently violating one of its bounds by more than the value of the optional parameter Feasibility Tolerance (default value=max 10-6,ε, where ε is the machine precision).
N | Not precisely optimal. The variable is nonbasic or superbasic. If the value of the reduced gradient for the variable exceeds the value of the optional parameter Optimality Tolerance (default value=max 10-6,ε), the solution would not be declared optimal because the reduced gradient for the variable would not be considered negligible.
Activity | is the value of vi at the final iterate.
Slack Activity | is the value by which vi differs from its nearest bound. (For the free row (if any), it is set to Activity.)
Lower Bound | is the lower bound specified for the variable. None indicates that BL j≤-bigbnd.
Upper Bound | is the upper bound specified for the variable. None indicates that BU j≥bigbnd.
i | gives the index i of vi.
Numerical values are output with a fixed number of digits; they are not guaranteed to be accurate to this precision.
H Chapter Contents
H Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


H02CFF : NAG Library, Mark 26

H Chapter Contents
H Chapter Introduction
NAG Library Manual

NAG Library Routine Document

H02CFF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

To supply optional parameters to H02CEF from an external file.

2 Specification

SUBROUTINE H02CFF ( IOPTNS, INFORM)
INTEGER IOPTNS, INFORM

3 Description

H02CFF may be used to supply values for optional parameters to H02CEF. H02CFF reads an external file and each line of the file defines a single optional parameter. It is only necessary to supply values for those arguments whose values are to be different from their default values.
Each optional parameter is defined by a single character string of up to 72 characters, consisting of one or more items. The items associated with a given option must be separated by spaces, or equal signs =. Alphabetic characters may be upper or lower case. The string
 Print level = 1
is an example of a string used to set an optional parameter. For each option the string contains one or more of the following items:
– | a mandatory keyword;
– | a phrase that qualifies the keyword;
– | a number that specifies an integer or real value. Such numbers may be up to 16 contiguous characters in Fortran 77's I, F, E or D formats, terminated by a space if this is not the last item on the line.
Blank strings and comments are ignored. A comment begins with an asterisk (*) and all subsequent characters in the string are regarded as part of the comment.
The file containing the options must start with Begin and must finish with End. An example of a valid options file is:
Begin * Example options file
Print Level = 1
End
Normally each line of the file is printed as it is read, on the current advisory message unit (see X04ABF), but printing may be suppressed using the keyword Nolist. To suppress printing of Begin, Nolist must be the first option supplied as in the file:
Begin
Nolist
Print Level = 1
End
Printing will automatically be turned on again after a call to H02CEF and may be turned on again at any time using the keyword List.
Optional parameter settings are preserved following a call to H02CEF, and so the keyword Defaults is provided to allow you to reset all the optional parameters to their default values prior to a subsequent call to H02CEF.
A complete list of optional parameters, their abbreviations, synonyms and default values is given in Section 12 in H02CEF.

4 References

None.

5 Arguments

1:   IOPTNS – INTEGERInput
On entry: the unit number of the options file to be read.
Constraint: 0≤IOPTNS≤99.
2:   INFORM – INTEGEROutput
On exit: contains zero if the options file has been successfully read and a value >0 otherwise, as indicated below.
INFORM=1
IOPTNS is not in the range 0,99.
INFORM=2
Begin was found, but end-of-file was found before End was found.
INFORM=3
end-of-file was found before Begin was found.

6 Error Indicators and Warnings

If a line is not recognized as a valid option, then a warning message is output on the current advisory message unit (see X04ABF).

7 Accuracy

Not applicable.

8 Parallelism and Performance

H02CFF is not thread safe and should not be called from a multithreaded user program. Please see Section 3.12.1 in How to Use the NAG Library and its Documentation for more information on thread safety.
H02CFF is not threaded in any implementation.

9 Further Comments

H02CGF may also be used to supply optional parameters to H02CEF. Note that if E04NKF/E04NKA is used in the same program as H02CEF, then in general H02CFF will also affect the options used by E04NKF/E04NKA.

10 Example

This example solves the same problem as the example for H02CEF, but in addition illustrates the use of H02CFF and H02CGF to set optional parameters for H02CEF.
In this example the options file read by H02CFF is appended to the data file for the program (see Section 10.2). It would usually be more convenient in practice to keep the data file and the options file separate.

10.1 Program Text

Program Text (h02cffe.f90)

10.2 Program Data

Program Options (h02cffe.opt)

Program Data (h02cffe.d)

10.3 Program Results

Program Results (h02cffe.r)

H Chapter Contents
H Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


H02CGF : NAG Library, Mark 26

H Chapter Contents
H Chapter Introduction
NAG Library Manual

NAG Library Routine Document

H02CGF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

To supply individual optional parameters to H02CEF.

2 Specification

SUBROUTINE H02CGF ( STR)
CHARACTER(*) STR

3 Description

H02CGF may be used to supply values for optional parameters to H02CEF. It is only necessary to call H02CGF for those arguments whose values are to be different from their default values. One call to H02CGF sets one argument value.
Each optional parameter is defined by a single character string of up to 72 characters, consisting of one or more items. The items associated with a given option must be separated by spaces, or equal signs =. Alphabetic characters may be upper or lower case. The string
 Print level = 1
is an example of a string used to set an optional parameter. For each option the string contains one or more of the following items:
– | a mandatory keyword;
– | a phrase that qualifies the keyword;
– | a number that specifies an integer or real value. Such numbers may be up to 16 contiguous characters in Fortran 77's I, F, E or D formats, terminated by a space if this is not the last item on the line.
Blank strings and comments are ignored. A comment begins with an asterisk (*) and all subsequent characters in the string are regarded as part of the comment.
Normally, each user-specified option is printed as it is defined, on the current advisory message unit (see X04ABF), but this printing may be suppressed using the keyword Nolist. Thus the statement
CALL H02CGF ('Nolist')
suppresses printing of this and subsequent options. Printing will automatically be turned on again after a call to H02CEF, and may be turned on again at any time using the keyword List.
Optional parameter settings are preserved following a call to H02CEF, and so the keyword Defaults is provided to allow you to reset all the optional parameters to their default values by the statement
CALL H02CGF ('Defaults')
prior to a subsequent call to H02CEF.
A complete list of optional parameters, their abbreviations, synonyms and default values is given in Section 12 in H02CEF.

4 References

None.

5 Arguments

1:   STR – CHARACTER(*)Input
On entry: a single valid option string (as described in Section 3 above and in Section 12 in H02CEF).

6 Error Indicators and Warnings

If a line is not recognized as a valid option, then a warning message is output on the current advisory message unit (see X04ABF).

7 Accuracy

Not applicable.

8 Parallelism and Performance

H02CGF is not thread safe and should not be called from a multithreaded user program. Please see Section 3.12.1 in How to Use the NAG Library and its Documentation for more information on thread safety.
H02CGF is not threaded in any implementation.

9 Further Comments

H02CFF may also be used to supply optional parameters to H02CEF. Note that if E04NKF/E04NKA is used in the same program as H02CEF, then in general H02CFF will also affect the options used by E04NKF/E04NKA.

10 Example

See Section 10 in H02CEF.
H Chapter Contents
H Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


H02DAF : NAG Library, Mark 26

H Chapter Contents
H Chapter Introduction
NAG Library Manual

NAG Library Routine Document

H02DAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results
▸▿ 11 Optional Parameters
11.1 Description of the Optional Parameters

1 Purpose

H02DAF solves general nonlinear programming problems with integer constraints on some of the variables.

2 Specification

SUBROUTINE H02DAF ( N, NCLIN, NCNLN, A, LDA, D, AX, BL, BU, VARCON, X, CONFUN, C, CJAC, OBJFUN, OBJGRD, MAXIT, ACC, OBJMIP, IOPTS, OPTS, IUSER, RUSER, IFAIL)
INTEGER | N, NCLIN, NCNLN, LDA, VARCON(N+NCLIN+NCNLN), MAXIT, IOPTS(*), IUSER(*), IFAIL
REAL (KIND=nag_wp) | A(LDA,*), D(NCLIN), AX(NCLIN), BL(N), BU(N), X(N), C(NCNLN), CJAC(NCNLN,N), OBJGRD(N), ACC, OBJMIP, OPTS(*), RUSER(*)
EXTERNAL | CONFUN, OBJFUN
Before calling H02DAF, H02ZKF must be called with OPTSTR set to ‘Initialize = h02daf’. Optional parameters may also be specified by calling H02ZKF before the call to H02DAF.

3 Description

H02DAF solves mixed integer nonlinear programming problems using a modified sequential quadratic programming method. The problem is assumed to be stated in the following general form:
minimize x∈ R nc,Z ni f x subject to cj x=0, j=1,2,…,me cj x≥0, j=me+1,me+2,…,m l≤xi≤u, i=1,2,…,n
with nc continuous variables and ni binary and integer variables in a total of n variables; me equality constraints in a total of m constraint functions.
Partial derivatives of f x and c x are not required for the ni integer variables. Gradients with respect to integer variables are approximated by difference formulae.
No assumptions are made regarding f x except that it is twice continuously differentiable with respect to continuous elements of x. It is not assumed that integer variables are relaxable. In other words, problem functions are evaluated only at integer points.
The method seeks to minimize the exact penalty function:
Pσ x = f x +σ g x ∞
where σ is adapted by the algorithm and g x is given by:
g x = cj x, j=1,2,…,me = min cj x,0, j=me+1,me+2,…,m.
Successive quadratic approximations are applied under the assumption that integer variables have a smooth influence on the model functions, that is function values do not change drastically when incrementing or decrementing an integer value. In practice this requires integer variables to be ordinal not categorical. The algorithm is stabilised by a trust region method including Yuan's second order corrections, see Yuan and Sun (2006). The Hessian of the Lagrangian function is approximated by BFGS (see Section 11.4 in E04UCF/E04UCA) updates subject to the continuous and integer variables.
The mixed-integer quadratic programming subproblems of the SQP-trust region method are solved by a branch and cut method with continuous subproblem solutions obtained by the primal-dual method of Goldfarb and Idnani, see Powell (1983). Different strategies are available for selecting a branching variable:
  • Maximal fractional branching. Select an integer variable from the relaxed subproblem solution with largest distance from next integer value
  • Minimal fractional branching. Select an integer variable from the relaxed subproblem solution with smallest distance from next integer value
and a node from where branching, that is the generation of two new subproblems, begins:
  • Best of two. The optimal objective function values of the two child nodes are compared and the node with a lower value is chosen
  • Best of all. Select an integer variable from the relaxed subproblem solution with the smallest distance from the next integer value
  • Depth first. Select a child node whenever possible.
This implementation is based on the algorithm MISQP as described in Exler et al. (2013).
Linear constraints may optionally be supplied by a matrix A and vector d rather than the constraint functions c x such that
Ax=d   or   ​ Ax≥d .
Partial derivatives with respect to x of these constraint functions are not requested by H02DAF.

4 References

Exler O, Lehmann T and Schittkowski K (2013) A comparative study of SQP-type algorithms for nonlinear and nonconvex mixed-integer optimization Mathematical Programming Computation 4 383–412
Mann A (1986) GAMS/MINOS: Three examples Department of Operations Research Technical Report Stanford University
Powell M J D (1983) On the quadratic programming algorithm of Goldfarb and Idnani Report DAMTP 1983/Na 19 University of Cambridge, Cambridge
Yuan Y-x and Sun W (2006) Optimization Theory and Methods Springer–Verlag

5 Arguments

1:   N – INTEGERInput
On entry: n, the total number of variables, nc+ni.
Constraint: N>0.
2:   NCLIN – INTEGERInput
On entry: nl, the number of general linear constraints defined by A and d.
Constraint: NCLIN≥0.
3:   NCNLN – INTEGERInput
On entry: nN, the number of constraints supplied by c x.
Constraint: NCNLN≥0.
4:   A LDA* – REAL (KIND=nag_wp) arrayInput
Note: the second dimension of the array A must be at least N if NCLIN>0.
On entry: the ith row of A must contain the coefficients of the ith general linear constraint, for i=1,2,…,nl. Any equality constraints must be specified first.
If NCLIN=0, the array A is not referenced.
5:   LDA – INTEGERInput
On entry: the first dimension of the array A as declared in the (sub)program from which H02DAF is called.
Constraint: LDA≥max 1,NCLIN.
6:   D NCLIN – REAL (KIND=nag_wp) arrayInput
On entry: di, the constant for the ith linear constraint.
If NCLIN=0, the array D is not referenced.
7:   AX NCLIN – REAL (KIND=nag_wp) arrayOutput
On exit: the final values of the linear constraints Ax.
If NCLIN=0, AX is not referenced.
8:   BL N – REAL (KIND=nag_wp) arrayInput
9:   BU N – REAL (KIND=nag_wp) arrayInput
On entry: BL must contain the lower bounds, li, and BU the upper bounds, ui, for the variables; bounds on integer variables are rounded, bounds on binary variables need not be supplied.
Constraint: BL i≤BU i, for i=1,2,…,N.
10:   VARCON N+NCLIN+NCNLN – INTEGER arrayInput
On entry: VARCON indicates the nature of each variable and constraint in the problem. The first n elements of the array must describe the nature of the variables, the next nL elements the nature of the general linear constraints (if any) and the next nN elements the general constraints (if any).
VARCON j=0
A continuous variable.
VARCON j=1
A binary variable.
VARCON j=2
An integer variable.
VARCON j=3
An equality constraint.
VARCON j=4
An inequality constraint.
Constraints:
  • VARCON j=0, 1 or 2, for j=1,2,…,N;
  • VARCON j=3 or 4, for j=N+1,…,N+NCLIN+NCNLN;
  • At least one variable must be either binary or integer;
  • Any equality constraints must precede any inequality constraints.
11:   X N – REAL (KIND=nag_wp) arrayInput/Output
On entry: an initial estimate of the solution, which need not be feasible. Values corresponding to integer variables are rounded; if an initial value less than half is supplied for a binary variable the value zero is used, otherwise the value one is used.
On exit: the final estimate of the solution.
12:   CONFUN – SUBROUTINE, supplied by the NAG Library or the user.External Procedure
CONFUN must calculate the constraint functions supplied by c x and their Jacobian at x. If all constraints are supplied by A and d (i.e., NCNLN=0), CONFUN will never be called by H02DAF and CONFUN may be the dummy routine H02DDM. (H02DDM is included in the NAG Library.) If NCNLN>0, the first call to CONFUN will occur after the first call to OBJFUN.
The specification of CONFUN is:
SUBROUTINE CONFUN ( MODE, NCNLN, N, VARCON, X, C, CJAC, NSTATE, IUSER, RUSER)
INTEGER | MODE, NCNLN, N, VARCON(*), NSTATE, IUSER(*)
REAL (KIND=nag_wp) | X(N), C(NCNLN), CJAC(NCNLN,N), RUSER(*)
1:   MODE – INTEGERInput/Output
On entry: indicates which values must be assigned during each call of OBJFUN. Only the following values need be assigned:
MODE=0
Elements of C containing continuous variables.
MODE=1
Elements of CJAC containing continuous variables.
On exit: may be set to a negative value if you wish to terminate the solution to the current problem, and in this case H02DAF will terminate with IFAIL set to MODE.
2:   NCNLN – INTEGERInput
On entry: the dimension of the array C and the first dimension of the array CJAC as declared in the (sub)program from which H02DAF is called. The number of constraints supplied by c x, nN.
3:   N – INTEGERInput
On entry: the second dimension of the array CJAC as declared in the (sub)program from which H02DAF is called. n, the total number of variables, nc+ni.
4:   VARCON* – INTEGER arrayInput
On entry: the array VARCON as supplied to H02DAF.
5:   X N – REAL (KIND=nag_wp) arrayInput
On entry: the vector of variables at which the objective function and/or all continuous elements of its gradient are to be evaluated.
6:   C NCNLN – REAL (KIND=nag_wp) arrayOutput
On exit: must contain NCNLN constraint values, with the value of the jth constraint cj x in C j.
7:   CJAC NCNLNN – REAL (KIND=nag_wp) arrayInput/Output
Note: the derivative of the ith constraint with respect to the jth variable, ∂ci ∂x j , is stored in CJAC ij.
On entry: continuous elements of CJAC are set to the value of NaN.
On exit: the ith row of CJAC must contain elements of ∂ci ∂x j for each continuous variable xj.
8:   NSTATE – INTEGERInput
On entry: if NSTATE=1, H02DAF is calling CONFUN for the first time. This argument setting allows you to save computation time if certain data must be read or calculated only once.
9:   IUSER* – INTEGER arrayUser Workspace
10:   RUSER* – REAL (KIND=nag_wp) arrayUser Workspace
CONFUN must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which H02DAF is called. Arguments denoted as Input must not be changed by this procedure.
13:   C NCNLN – REAL (KIND=nag_wp) arrayOutput
On exit: if NCNLN>0, C j contains the value of the jth constraint function cj x at the final iterate, for j=1,2,…,NCNLN.
If NCNLN=0, the array C is not referenced.
14:   CJAC NCNLNN – REAL (KIND=nag_wp) arrayOutput
Note: the derivative of the ith constraint with respect to the jth variable, ∂ci ∂x j , is stored in CJAC ij.
On exit: if NCNLN>0, CJAC contains the Jacobian matrix of the constraint functions at the final iterate, i.e., CJAC ij contains the partial derivative of the ith constraint function with respect to the jth variable, for i=1,2,…,NCNLN and j=1,2,…,N. (See the discussion of argument CJAC under CONFUN.)
If NCNLN=0, the array CJAC is not referenced.
15:   OBJFUN – SUBROUTINE, supplied by the user.External Procedure
OBJFUN must calculate the objective function f x and its gradient for a specified n-element vector x.
The specification of OBJFUN is:
SUBROUTINE OBJFUN ( MODE, N, VARCON, X, OBJMIP, OBJGRD, NSTATE, IUSER, RUSER)
INTEGER | MODE, N, VARCON(*), NSTATE, IUSER(*)
REAL (KIND=nag_wp) | X(N), OBJMIP, OBJGRD(N), RUSER(*)
1:   MODE – INTEGERInput/Output
On entry: indicates which values must be assigned during each call of OBJFUN. Only the following values need be assigned:
MODE=0
The objective function value, OBJMIP.
MODE=1
The continuous elements of OBJGRD.
On exit: may be set to a negative value if you wish to terminate the solution to the current problem, and in this case H02DAF will terminate with IFAIL set to MODE.
2:   N – INTEGERInput
On entry: n, the total number of variables, nc+ni.
3:   VARCON* – INTEGER arrayInput
On entry: the array VARCON as supplied to H02DAF.
4:   X N – REAL (KIND=nag_wp) arrayInput
On entry: the vector of variables at which the objective function and/or all continuous elements of its gradient are to be evaluated.
5:   OBJMIP – REAL (KIND=nag_wp)Output
On exit: must be set to the objective function value, f, if MODE=0; otherwise OBJMIP is not referenced.
6:   OBJGRD N – REAL (KIND=nag_wp) arrayInput/Output
On entry: continuous elements of OBJGRD are set to the value of NaN.
On exit: must contain the gradient vector of the objective function if MODE=1, with OBJGRD j containing the partial derivative of f with respect to continuous variable xj; otherwise OBJGRD is not referenced.
7:   NSTATE – INTEGERInput
On entry: if NSTATE=1, H02DAF is calling OBJFUN for the first time. This argument setting allows you to save computation time if certain data must be read or calculated only once.
8:   IUSER* – INTEGER arrayUser Workspace
9:   RUSER* – REAL (KIND=nag_wp) arrayUser Workspace
OBJFUN is called with the arguments IUSER and RUSER as supplied to H02DAF. You are free to use the arrays IUSER and RUSER to supply information to OBJFUN as an alternative to using COMMON global variables.
OBJFUN must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which H02DAF is called. Arguments denoted as Input must not be changed by this procedure.
16:   OBJGRD N – REAL (KIND=nag_wp) arrayOutput
On exit: the objective function gradient at the solution.
17:   MAXIT – INTEGERInput
On entry: the maximum number of iterations within which to find a solution. If MAXIT is less than or equal to zero, the suggested value below is used.
Suggested value: MAXIT=500.
18:   ACC – REAL (KIND=nag_wp)Input
On entry: the requested accuracy for determining feasible points during iterations and for halting the method when the predicted improvement in objective function is less than ACC. If ACC is less than or equal to ε (ε being the machine precision as given by X02AJF), the below suggested value is used.
Suggested value: ACC=0.0001.
19:   OBJMIP – REAL (KIND=nag_wp)Output
On exit: with IFAIL=0, OBJMIP contains the value of the objective function for the MINLP solution.
20:   IOPTS* – INTEGER arrayCommunication Array
Note: the dimension of this array is dictated by the requirements of associated functions that must have been previously called. This array must be the same array passed as argument IOPTS in the previous call to H02ZKF.
21:   OPTS* – REAL (KIND=nag_wp) arrayCommunication Array
Note: the dimension of this array is dictated by the requirements of associated functions that must have been previously called. This array must be the same array passed as argument OPTS in the previous call to H02ZKF.
On entry: the real option array as returned by H02ZKF.
22:   IUSER* – INTEGER arrayUser Workspace
23:   RUSER* – REAL (KIND=nag_wp) arrayUser Workspace
IUSER and RUSER are not used by H02DAF, but are passed directly to CONFUN and OBJFUN and may be used to pass information to these routines as an alternative to using COMMON global variables.
24:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, N=value.
Constraint: N>0.
IFAIL=2
On entry, NCLIN=value.
Constraint: NCLIN≥0.
IFAIL=3
On entry, NCNLN=value.
Constraint: NCNLN≥0.
IFAIL=4
On entry, LDA=value and NCLIN=value.
Constraint: LDA≥NCLIN.
IFAIL=5
On entry, BL value>BU value.
Constraint: BL i≤BU i, for i=1,2,…,N.
IFAIL=6
On entry, VARCON value=value.
Constraint: VARCON i=0, 1 or 2, for i=1,2,…,N.
IFAIL=7
On entry, VARCON value=value.
Constraint: VARCON i=3 or 4, for i=N+1,…,N+NCLIN+NCNLN.
IFAIL=8
The supplied OBJFUN returned a NaN value.
IFAIL=9
The supplied CONFUN returned a NaN value.
IFAIL=10
On entry, the optional parameter arrays IOPTS and OPTS have either not been initialized or been corrupted.
IFAIL=11
On entry, there are no binary or integer variables.
IFAIL=12
On entry, linear equality constraints do not precede linear inequality constraints.
IFAIL=13
On entry, nonlinear equality constraints do not precede nonlinear inequality constraints.
IFAIL=81
One or more objective gradients appear to be incorrect.
IFAIL=91
One or more constraint gradients appear to be incorrect.
IFAIL=1001
On entry, MAXIT=value. Exceeded the maximum number of iterations.
IFAIL=1002
More than the maximum number of feasible steps without improvement in the objective function. If the maximum number of feasible steps is small, say less than 5, try increasing it. Optional parameter Feasible Steps=value.
IFAIL=1003
Penalty parameter tends to infinity in an underlying mixed-integer quadratic program; the problem may be infeasible. If σ is relatively low value, try a higher one, for example 1020.
Optional parameter Penalty=value.
IFAIL=1004
Termination at an infeasible iterate; if the problem is feasible, try a different starting value.
IFAIL=1005
Termination with zero integer trust region for integer variables; try a different starting value.
Optional parameter Integer Trust Radius=value.
IFAIL=1008
The optimization failed due to numerical difficulties. Set optional parameter Print Level=3 for more information.
IFAIL<0
The optimization halted because you set MODE negative in OBJFUN or MODE negative in CONFUN, to value.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

H02DAF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

None.

10 Example

Select a portfolio of at most p assets from n available with expected return ρ, is fully invested and that minimizes
xT Σx subject to  rT x = ρ ∑ i=1 n xi = 1 xi ≤ yi ∑ i=1 n yi ≤ p xi ≥ 0 yi = 0 or 1
where
  • x is a vector of proportions of selected assets
  • y is an indicator variable that describes if an asset is in or out
  • r is a vector of mean returns
  • Σ is the covariance matrix of returns.
This example is taken from Mann (1986) with
r = 89127 Σ = 43-10 3610 -11100 0000 p = 3 ρ = 10.
Linear constraints are supplied through both A and d, and CONFUN.

10.1 Program Text

Program Text (h02dafe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (h02dafe.r)

11 Optional Parameters

This section can be skipped if you wish to use the default values for all optional parameters, otherwise, the following is a list of the optional parameters available and a full description of each optional parameter is provided in Section 11.1.
  • Branch Bound Steps
  • Branching Rule
  • Check Gradients
  • Continuous Trust Radius
  • Descent
  • Descent Factor
  • Feasible Steps
  • Improved Bounds
  • Integer Trust Radius
  • Maximum Restarts
  • Minor Print Level
  • Modify Hessian
  • Node Selection
  • Non Monotone
  • Objective Scale Bound
  • Penalty
  • Penalty Factor
  • Print Level
  • QP Accuracy
  • Scale Continuous Variables
  • Scale Objective Function
  • Warm Starts

11.1 Description of the Optional Parameters

For each option, we give a summary line, a description of the optional parameter and details of constraints.
The summary line contains:
  • the keywords;
  • a parameter value, where the letters a, i and r denote options that take character, integer and real values respectively.
All options accept the value DEFAULT in order to return single options to their default states.
Keywords and character values are case insensitive, however they must be separated by at least one space.
H02ZKF can be called to supply options, one call being necessary for each optional parameter. For example,
Call H02ZKF('Check Gradients = Yes', iopts, liopts, opts, lopts, ifail)
H02ZKF should be consulted for a full description of the method of supplying optional parameters.
For H02DAF the maximum length of the argument CVALUE used by H02ZLF is 12.
Branch Bound Steps i Default=500
Maximum number of branch-and-bound steps for solving the mixed integer quadratic problems.
Constraint: Branch Bound Steps>1.
Branching Rule a Default=Maximum
Branching rule for branch and bound search.
Branching Rule=Maximum
Maximum fractional branching.
Branching Rule=Minimum
Minimum fractional branching.
Check Gradients a Default=No
Perform an internal check of supplied objective and constraint gradients. It is advisable to set Check Gradients=Yes during code development to avoid difficulties associated with incorrect user-supplied gradients.
Continuous Trust Radius r Default=10.0
Initial continuous trust region radius, Δ 0 c; the initial trial step d∈R nc for the SQP approximation must satisfy d∞ ≤Δ 0 c.
Constraint: Continuous Trust Radius>0.0.
Descent r Default=0.05
Initial descent parameter, δ, larger values of δ allow penalty optional parameter σ to increase faster which can lead to faster convergence.
Constraint: 0.0<Descent<1.0.
Descent Factor r Default=0.1
Factor for decreasing the internal descent parameter, δ, between iterations.
Constraint: 0.0<Descent Factor<1.0.
Feasible Steps i Default=10
Maximum number of feasible steps without improvements, where feasibility is measured by g x∞≤ACC.
Constraint: Feasible Steps>1.
Improved Bounds a Default=No
Calculate improved bounds in case of ‘Best of all’ node selection strategy.
Integer Trust Radius r Default=10.0
Initial integer trust region radius, Δ 0 i; the initial trial step e∈R ni for the SQP approximation must satisfy e∞≤Δ 0 i.
Constraint: Integer Trust Radius≥1.0.
Maximum Restarts i Default=2
Maximum number of restarts that allow the mixed integer SQP algorithm to return to a better solution. Setting a value higher than the default might lead to better results at the expense of function evaluations.
Constraint: 0<Maximum Restarts≤15.
Minor Print Level i Default=0
Print level of the subproblem solver. Active only if Print Level≠0.
Constraint: 0<Minor Print Level<4.
Modify Hessian a Default=Yes
Modify the Hessian approximation in an attempt to get more accurate search directions. Calculation time is increased when the number of integer variables is large.
Node Selection a Default=Depth First
Node selection strategy for branch and bound.
Node Selection=Best of all
Large tree search; this method is the slowest as it solves all subproblem QPs independently.
Node Selection=Best of two
Uses warm starts and less memory.
Node Selection=Depth first
Uses more warm starts. If warm starts are applied, they can speed up the solution of mixed integer subproblems significantly when solving almost identical QPs.
Non Monotone i Default=10
Maximum number of successive iterations considered for the non-monotone trust region algorithm, allowing the penalty function to increase.
Constraint: 0<Non Monotone<100.
Objective Scale Bound r Default=1.0
When Scale Objective Function>0 internally scale absolute function values greater than 1.0 or Objective Scale Bound.
Constraint: Objective Scale Bound>0.0.
Penalty r Default=1000.0
Initial penalty optional parameter, σ.
Constraint: Penalty≥0.0.
Penalty Factor r Default=10.0
Factor for increasing penalty optional parameter σ when the trust regions cannot be enlarged at a trial step.
Constraint: Penalty Factor>1.0.
Print Level i Default=0
Specifies the desired output level of printing.
Print Level=0
No output.
Print Level=1
Final convergence analysis.
Print Level=2
One line of intermediate results per iteration.
Print Level=3
Detailed information printed per iteration.
QP Accuracy r Default=1.0E−10
Termination tolerance of the relaxed quadratic program subproblems.
Constraint: QP Accuracy>0.0.
Scale Continuous Variables a Default=Yes
Internally scale continuous variables values.
Scale Objective Function i Default=1
Internally scale objective function values.
Scale Objective Function=0
No scaling.
Scale Objective Function=1
Scale absolute values greater than Objective Scale Bound.
Warm Starts i Default=100
Maximum number of warm starts within the mixed integer QP solver, see Node Selection.
Constraint: Warm Starts≥0.
H Chapter Contents
H Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


H02ZKF : NAG Library, Mark 26

H Chapter Contents
H Chapter Introduction
NAG Library Manual

NAG Library Routine Document

H02ZKF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

H02ZKF either initializes or resets the optional parameter arrays or sets a single optional parameter for supported problem solving routines in Chapter H.
Currently, only H02DAF is supported.

2 Specification

SUBROUTINE H02ZKF ( OPTSTR, IOPTS, LIOPTS, OPTS, LOPTS, IFAIL)
INTEGER | IOPTS(LIOPTS), LIOPTS, LOPTS, IFAIL
REAL (KIND=nag_wp) | OPTS(LOPTS)
CHARACTER(*) | OPTSTR

3 Description

H02ZKF has three purposes: to initialize optional parameter arrays; to reset all optional parameters to their default values; or to set a single optional parameter to a user-supplied value.
Optional parameters and their values are, in general, presented as a character string, OPTSTR, of the form ‘option =optval’; alphabetic characters can be supplied in either upper or lower case. Both option and optval may consist of one or more tokens separated by white space. The tokens that comprise optval will normally be either an integer, real or character value as defined in the description of the specific optional argument. In addition all optional parameters can take an optval DEFAULT which resets the optional parameter to its default value.
It is imperative that optional parameter arrays are initialized before any options are set, before the relevant problem solving routine is called and before any options are queried using H02ZLF. To initialize the optional parameter arrays IOPTS and OPTS for a specific problem solving routine, the option Initialize is used with optval identifying the problem solving routine to be called, via its short name. For example, to initialize optional parameter arrays to be passed to H02DAF, H02ZKF is called as follows:
call H02ZKF('Initialize = h02daf', IOPTS, LIOPTS, OPTS, LOPTS, IFAIL)
Information relating to available option names and their corresponding valid values is given in Section 11 in H02DAF.

4 References

None.

5 Arguments

1:   OPTSTR – CHARACTER(*)Input
On entry: a string identifying the option to be set.
Initialize=routine name
Initialize the optional parameter arrays IOPTS and OPTS for use with routine routine name, where routine name is the short name associated with the routine of interest.
Defaults
Resets all options to their default values.
option=optval
See Section 11 in H02DAF for details of valid values for option and optval. The equals sign (=) delimiter must be used to separate the option from its optval value.
OPTSTR is case insensitive. Each token in the option and optval component must be separated by at least one space.
2:   IOPTS LIOPTS – INTEGER arrayCommunication Array
3:   LIOPTS – INTEGERInput
On entry: the length of the array IOPTS.
Constraint: unless otherwise stated in the documentation for a specific, supported, problem solving routine, LIOPTS≥200.
4:   OPTS LOPTS – REAL (KIND=nag_wp) arrayCommunication Array
5:   LOPTS – INTEGERInput
On entry: the length of the array OPTS.
Constraint: unless otherwise stated in the documentation for a specific, supported, problem solving routine, LOPTS≥100.
6:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=11
On entry, the optional parameter in OPTSTR was not recognized: OPTSTR=value.
IFAIL=12
On entry, the expected delimiter ‘=’ was not found in OPTSTR: OPTSTR=value.
IFAIL=13
On entry, could not convert the specified optval to an integer: OPTSTR=value.
On entry, could not convert the specified optval to a real: OPTSTR=value.
IFAIL=14
On entry, attempting to initialize the optional parameter arrays but specified routine name was not valid: name=value.
IFAIL=15
On entry, the optval supplied for the integer optional parameter is not valid.
OPTSTR=value.
IFAIL=16
On entry, the optval supplied for the real optional parameter is not valid.
OPTSTR=value.
IFAIL=17
On entry, the optval supplied for the character optional parameter is not valid.
OPTSTR=value.
IFAIL=21
On entry, either the option arrays have not been initialized or they have been corrupted.
IFAIL=31
On entry, LIOPTS=value.
Constraint: LIOPTS≥value.
IFAIL=51
On entry, LOPTS=value.
Constraint: LOPTS≥value.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

H02ZKF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

None.

10 Example

See the example programs associated with the problem solving routine you wish to use for a demonstration of how to use H02ZKF to initialize option arrays and set options.
H Chapter Contents
H Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


H02ZLF : NAG Library, Mark 26

H Chapter Contents
H Chapter Introduction
NAG Library Manual

NAG Library Routine Document

H02ZLF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

H02ZLF is used to query the value of optional parameters available to supported problem solving routines in Chapter H.
Currently, only H02DAF is supported.

2 Specification

SUBROUTINE H02ZLF ( OPTSTR, IVALUE, RVALUE, CVALUE, OPTYPE, IOPTS, OPTS, IFAIL)
INTEGER | IVALUE, OPTYPE, IOPTS(*), IFAIL
REAL (KIND=nag_wp) | RVALUE, OPTS(*)
CHARACTER(*) | OPTSTR, CVALUE

3 Description

H02ZLF is used to query the current values of options. It is necessary to initialize optional parameter arrays using H02ZKF before any options are queried.
H02ZLF will normally return either an integer, real or character value dependent upon the type associated with the optional parameter being queried. Some real and integer options also return additional information in CVALUE. Whether the option queried is of integer, real or character type, and whether additional information is returned in CVALUE, is indicated by the returned value of OPTYPE.
Information on optional parameter names and whether these options are real, integer or character can be found in Section 11 in H02DAF.

4 References

None.

5 Arguments

1:   OPTSTR – CHARACTER(*)Input
On entry: a string identifying the option whose current value is required. See Section 11 in H02DAF for information on valid options. In addition, the following is a valid option:
Identify
H02ZLF returns in CVALUE the routine name supplied to H02ZKF when the optional parameter arrays IOPTS and OPTS were initialized.
2:   IVALUE – INTEGEROutput
On exit: if the optional parameter supplied in OPTSTR is an integer valued argument, IVALUE will hold its current value.
3:   RVALUE – REAL (KIND=nag_wp)Output
On exit: if the optional parameter supplied in OPTSTR is a real valued argument, RVALUE will hold its current value.
4:   CVALUE – CHARACTER(*)Output
Note: the string returned in CVALUE will never exceed 40 characters in length.
On exit: if the optional parameter supplied in OPTSTR is a character valued argument, CVALUE will hold its current value. CVALUE will also contain additional information for some integer and real valued arguments, as indicated by OPTYPE.
5:   OPTYPE – INTEGEROutput
On exit: indicates whether the optional parameter supplied in OPTSTR is an integer, real or character valued argument and hence which of IVALUE, RVALUE or CVALUE holds the current value.
OPTYPE=1
OPTSTR is an integer valued optional parameter, its current value has been returned in IVALUE.
OPTYPE=2
OPTSTR is a real valued optional parameter, its current value has been returned in RVALUE.
OPTYPE=3
OPTSTR is a character valued optional parameter, its current value has been returned in CVALUE.
OPTYPE=4
OPTSTR is an integer valued optional parameter, its current value has been returned in IVALUE. Additional information has been returned in CVALUE.
OPTYPE=5
OPTSTR is a real valued optional parameter, its current value has been returned in RVALUE. Additional information has been returned in CVALUE.
6:   IOPTS* – INTEGER arrayCommunication Array
Note: the dimension of this array is dictated by the requirements of associated functions that must have been previously called. This array must be the same array passed as argument IOPTS in the previous call to H02ZKF.
7:   OPTS* – REAL (KIND=nag_wp) arrayCommunication Array
Note: the dimension of this array is dictated by the requirements of associated functions that must have been previously called. This array must be the same array passed as argument OPTS in the previous call to H02ZKF.
8:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=11
On entry, the option in OPTSTR has not been recognized.
IFAIL=41
On entry, OPTSTR indicates a character optional parameter, but CVALUE is too short to hold the stored value. The returned value will be truncated.
IFAIL=61
The arrays IOPTS and OPTS have either not been initialized, have become corrupted, or are not compatible with this option setting routine.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

H02ZLF is not threaded in any implementation.

9 Further Comments

None.

10 Example

See the example programs associated with the problem solving routine you wish to use for a demonstration of how to use H02ZLF to query options.
H Chapter Contents
H Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


H03ABF : NAG Library, Mark 26

H Chapter Contents
H Chapter Introduction
NAG Library Manual

NAG Library Routine Document

H03ABF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

H03ABF solves the classical Transportation (‘Hitchcock’) problem.

2 Specification

SUBROUTINE H03ABF ( KOST, LDKOST, MA, MB, M, K15, MAXIT, K7, K9, NUMIT, K6, K8, K11, K12, Z, IFAIL)
INTEGER | KOST(LDKOST,MB), LDKOST, MA, MB, M, K15(M), MAXIT, K7(M), K9(M), NUMIT, K6(M), K8(M), K11(M), K12(M), IFAIL
REAL (KIND=nag_wp) | Z

3 Description

H03ABF solves the Transportation problem by minimizing
z = ∑ i ma ∑ j mb c ij x ij .
subject to the constraints
∑ j mb x i j = A i   (Availabilities) ∑ i ma ∑ i x i j = B j   (Requirements)
where the x ij can be interpreted as quantities of goods sent from source i to destination j, for i=1,2,…,ma and j=1,2,…,mb, at a cost of c ij per unit, and it is assumed that ∑ i ma Ai= ∑ j mb ∑j Bj and x ij≥0.
H03ABF uses the ‘stepping stone’ method, modified to accept degenerate cases.

4 References

Hadley G (1962) Linear Programming Addison–Wesley

5 Arguments

1:   KOST LDKOSTMB – INTEGER arrayInput
On entry: the coefficients c ij, for i=1,2,…,ma and j=1,2,…,mb.
2:   LDKOST – INTEGERInput
On entry: the first dimension of the array KOST as declared in the (sub)program from which H03ABF is called.
Constraint: LDKOST≥MA.
3:   MA – INTEGERInput
On entry: the number of sources, ma.
Constraint: MA≥1.
4:   MB – INTEGERInput
On entry: the number of destinations, mb.
Constraint: MB≥1.
5:   M – INTEGERInput
On entry: the value of ma+mb.
6:   K15 M – INTEGER arrayInput/Output
On entry: K15 i must be set to the availabilities Ai, for i=1,2,…,ma; and K15 ma+j must be set to the requirements Bj, for j=1,2,…,mb.
On exit: the contents of K15 are undefined.
7:   MAXIT – INTEGERInput
On entry: the maximum number of iterations allowed.
Constraint: MAXIT≥1.
8:   K7 M – INTEGER arrayWorkspace
9:   K9 M – INTEGER arrayWorkspace
10:   NUMIT – INTEGEROutput
On exit: the number of iterations performed.
11:   K6 M – INTEGER arrayOutput
On exit: K6 k, for k=1,2,…,ma+mb-1, contains the source indices of the optimal solution (see K11).
12:   K8 M – INTEGER arrayOutput
On exit: K8 k, for k=1,2,…,ma+mb-1, contains the destination indices of the optimal solution (see K11).
13:   K11 M – INTEGER arrayOutput
On exit: K11 k, for k=1,2,…,ma+mb-1, contains the optimal quantities x ij which, sent from source i=K6 k to destination j=K8 k, minimize z.
14:   K12 M – INTEGER arrayOutput
On exit: K12 k, for k=1,2,…,ma+mb-1, contains the unit cost c ij associated with the route from source i=K6 k to destination j=K8 k.
15:   Z – REAL (KIND=nag_wp)Output
On exit: the value of the minimized total cost.
16:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, the sum of the availabilities does not equal the sum of the requirements.
IFAIL=2
During computation MAXIT has been exceeded.
IFAIL=3
On entry, MAXIT<1.
IFAIL=4
On entry, | MA<1,
or | MB<1,
or | M≠MA+MB,
or | MA>LDKOST.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

All operations are performed in integer arithmetic so that there are no rounding errors.

8 Parallelism and Performance

H03ABF is not threaded in any implementation.

9 Further Comments

An accurate estimate of the run time for a particular problem is difficult to achieve.

10 Example

A company has three warehouses and three stores. The warehouses have a surplus of 12 units of a given commodity divided among them as follows:
Warehouse | Surplus
1 | 1
2 | 5
3 | 6
The stores altogether need 12 units of commodity, with the following requirements:
Store | Requirement
1 | 4
2 | 4
3 | 4
Costs of shipping one unit of the commodity from warehouse i to store j are displayed in the following matrix:
 |  | Store
 |  | 1 | 2 | 3
 | 1 | 8 | 8 | 11
Warehouse | 2 | 5 | 8 | 14
 | 3 | 4 | 3 | 10
It is required to find the units of commodity to be moved from the warehouses to the stores, such that the transportation costs are minimized. The maximum number of iterations allowed is 200.

10.1 Program Text

Program Text (h03abfe.f90)

10.2 Program Data

Program Data (h03abfe.d)

10.3 Program Results

Program Results (h03abfe.r)

H Chapter Contents
H Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


H03ADF : NAG Library, Mark 26

H Chapter Contents
H Chapter Introduction
NAG Library Manual

NAG Library Routine Document

H03ADF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

H03ADF finds the shortest path through a directed or undirected acyclic network using Dijkstra's algorithm.

2 Specification

SUBROUTINE H03ADF ( N, NS, NE, DIRECT, NNZ, D, IROW, ICOL, SPLEN, PATH, IWORK, WORK, IFAIL)
INTEGER | N, NS, NE, NNZ, IROW(NNZ), ICOL(NNZ), PATH(N), IWORK(3*N+1), IFAIL
REAL (KIND=nag_wp) | D(NNZ), SPLEN, WORK(2*N)
LOGICAL | DIRECT

3 Description

H03ADF attempts to find the shortest path through a directed or undirected acyclic network, which consists of a set of points called vertices and a set of curves called arcs that connect certain pairs of distinct vertices. An acyclic network is one in which there are no paths connecting a vertex to itself. An arc whose origin vertex is i and whose destination vertex is j can be written as i→j. In an undirected network the arcs i→j and j→i are equivalent (i.e., i↔j), whereas in a directed network they are different. Note that the shortest path may not be unique and in some cases may not even exist (e.g., if the network is disconnected).
The network is assumed to consist of n vertices which are labelled by the integers 1,2,…,n. The lengths of the arcs between the vertices are defined by the n by n distance matrix D, in which the element d ij gives the length of the arc i→j; d ij=0 if there is no arc connecting vertices i and j (as is the case for an acyclic network when i=j). Thus the matrix D is usually sparse. For example, if n=4 and the network is directed, then
D= 0 d 12 d 13 d 14 d 21 0 d 23 d 24 d 31 d 32 0 d 34 d 41 d 42 d 43 0 .
If the network is undirected, D is symmetric since d ij=d ji (i.e., the length of the arc i→j≡ the length of the arc j→i).
The method used by H03ADF is described in detail in Section 9.

4 References

Dijkstra E W (1959) A note on two problems in connection with graphs Numer. Math. 1 269–271

5 Arguments

1:   N – INTEGERInput
On entry: n, the number of vertices.
Constraint: N≥2.
2:   NS – INTEGERInput
3:   NE – INTEGERInput
On entry: ns and ne, the labels of the first and last vertices, respectively, between which the shortest path is sought.
Constraints:
  • 1≤NS≤N;
  • 1≤NE≤N;
  • NS≠NE.
4:   DIRECT – LOGICALInput
On entry: indicates whether the network is directed or undirected.
DIRECT=.TRUE.
The network is directed.
DIRECT=.FALSE.
The network is undirected.
5:   NNZ – INTEGERInput
On entry: the number of nonzero elements in the distance matrix D.
Constraints:
  • if DIRECT=.TRUE., 1≤NNZ≤N×N-1;
  • if DIRECT=.FALSE., 1≤NNZ≤N×N-1/2.
6:   D NNZ – REAL (KIND=nag_wp) arrayInput
On entry: the nonzero elements of the distance matrix D, ordered by increasing row index and increasing column index within each row. More precisely, D k must contain the value of the nonzero element with indices (IROW k,ICOL k); this is the length of the arc from the vertex with label IROW k to the vertex with label ICOL k. Elements with the same row and column indices are not allowed. If DIRECT=.FALSE., then only those nonzero elements in the strict upper triangle of D need be supplied since d ij=d ji. (F11ZAF may be used to sort the elements of an arbitrarily ordered matrix into the required form. This is illustrated in Section 10.)
Constraint: D k>0.0, for k=1,2,…,NNZ.
7:   IROW NNZ – INTEGER arrayInput
8:   ICOL NNZ – INTEGER arrayInput
On entry: IROW k and ICOL k must contain the row and column indices, respectively, for the nonzero element stored in D k.
Constraints:
IROW and ICOL must satisfy the following constraints (which may be imposed by a call to F11ZAF):
  • IROW k-1<IROW k;
  • IROW k-1=IROW k and ICOL k-1<ICOL k, for k=2,3,…,NNZ.
In addition, if DIRECT=.TRUE., 1≤IROW k≤N, 1≤ICOL k≤N and IROW k≠ICOL k;
  • if DIRECT=.FALSE., 1≤IROW k<ICOL k≤N.
9:   SPLEN – REAL (KIND=nag_wp)Output
On exit: the length of the shortest path between the specified vertices ns and ne.
10:   PATH N – INTEGER arrayOutput
On exit: contains details of the shortest path between the specified vertices ns and ne. More precisely, NS=PATH 1→PATH 2→…→PATH p=NE for some p≤n. The remaining n-p elements are set to zero.
11:   IWORK 3×N+1 – INTEGER arrayWorkspace
12:   WORK 2×N – REAL (KIND=nag_wp) arrayWorkspace
13:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | N<2,
or | NS<1,
or | NS>N,
or | NE<1,
or | NE>N,
or | NS=NE.
IFAIL=2
On entry, | NNZ>N×N-1 when DIRECT=.TRUE.,
or | NNZ>N×N-1/2 when DIRECT=.FALSE.,
or | NNZ<1.
IFAIL=3
On entry, IROW k<1 or IROW k>N or ICOL k<1 or ICOL k>N or IROW k=ICOL k for some k when DIRECT=.TRUE..
IFAIL=4
On entry, IROW k<1 or IROW k≥ICOL k or ICOL k>N for some k when DIRECT=.FALSE..
IFAIL=5
D k≤0.0 for some k.
IFAIL=6
On entry, IROW k-1>IROW k or IROW k-1=IROW k and ICOL k-1>ICOL k for some k.
IFAIL=7
On entry, IROW k-1=IROW k and ICOL k-1=ICOL k for some k.
IFAIL=8
No connected network exists between vertices NS and NE.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The results are exact, except for the obvious rounding errors in summing the distances in the length of the shortest path.

8 Parallelism and Performance

H03ADF is not threaded in any implementation.

9 Further Comments

H03ADF is based upon Dijkstra's algorithm (see Dijkstra (1959)), which attempts to find a path ns→ne between two specified vertices ns and ne of shortest length d ns,ne.
The algorithm proceeds by assigning labels to each vertex, which may be temporary or permanent. A temporary label can be changed, whereas a permanent one cannot. For example, if vertex p has a permanent label q,r, then r is the distance d ns,r and q is the previous vertex on a shortest length ns→p path. If the label is temporary, then it has the same meaning but it refers only to the shortest ns→p path found so far. A shorter one may be found later, in which case the label may become permanent.
The algorithm consists of the following steps.
1. | Assign the permanent label -,0 to vertex ns and temporary labels -,∞ to every other vertex. Set k=ns and go to 2.
2. | Consider each vertex y adjacent to vertex k with a temporary label in turn. Let the label at k be p,q and at y r,s. If q+d ky<s, then a new temporary label k,q+d ky is assigned to vertex y; otherwise no change is made in the label of y. When all vertices y with temporary labels adjacent to k have been considered, go to 3.
3. | From the set of temporary labels, select the one with the smallest second component and declare that label to be permanent. The vertex it is attached to becomes the new vertex k. If k=ne go to 4. Otherwise go to 2 unless no new vertex can be found (e.g., when the set of temporary labels is ‘empty’ but k≠ne, in which case no connected network exists between vertices ns and ne).
4. To find the shortest path, let y,z denote the label of vertex ne. The column label (z) gives d ns,ne while the row label (y) then links back to the previous vertex on a shortest length ns→ne path. Go to vertex y. Suppose that the (permanent) label of vertex y is w,x, then the next previous vertex is w on a shortest length ns→y path. This process continues until vertex ns is reached. Hence the shortest path is
ns→…→w→y→ne,
which has length d ns,ne.

10 Example

This example finds the shortest path between vertices 1 and 11 for the undirected network
Figure 1

10.1 Program Text

Program Text (h03adfe.f90)

10.2 Program Data

Program Data (h03adfe.d)

10.3 Program Results

Program Results (h03adfe.r)

H Chapter Contents
H Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


H03BBF : NAG Library, Mark 26

H Chapter Contents
H Chapter Introduction
NAG Library Manual

NAG Library Routine Document

H03BBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

H03BBF calculates an approximate solution to a symmetric travelling salesman problem using simulated annealing via a configuration free interface.

2 Specification

SUBROUTINE H03BBF ( NC, DM, BOUND, TARGC, PATH, COST, TMODE, ALG_STATS, STATE, IFAIL)
INTEGER | NC, PATH(NC), TMODE, STATE(*), IFAIL
REAL (KIND=nag_wp) | DM(NC,NC), BOUND, TARGC, COST, ALG_STATS(6)

3 Description

H03BBF provides a probabilistic strategy for the calculation of a near optimal path through a symmetric and fully connected distance matrix; that is, a matrix for which element i,j is the pairwise distance (also called the cost, or weight) between nodes (cities) i and j. This problem is better known as the Travelling Salesman Problem (TSP), and symmetric means that the distance to travel between two cities is independent of which is the destination city.
In the classical TSP, which this routine addresses, a salesman wishes to visit a given set of cities once only by starting and finishing in a home city and travelling the minimum total distance possible. It is one of the most intensively studied problems in computational mathematics and, as a result, has developed some fairly sophisticated techniques for getting near-optimal solutions for large numbers of cities. H03BBF adopts a very simple approach to try to find a reasonable solution, for moderately large problems. The routine uses simulated annealing: a stochastic mechanical process in which the heating and controlled cooling of a material is used to optimally refine its molecular structure.
The material in the TSP is the distance matrix and a given state is represented by the order in which each city is visited—the path. This system can move from one state to a neighbouring state by selecting two cities on the current path at random and switching their places; the order of the cities in the path between the switched cities is then reversed. The cost of a state is the total cost of traversing its path; the resulting difference in cost between the current state and this new proposed state is called the delta; a negative delta indicates the proposal creates a more optimal path and a positive delta a less optimal path. The random selection of cities to switch uses random number generators (RNGs) from Chapter G05; it is thus necessary to initialize a state array for the RNG of choice (by a call to G05KFF or G05KGF) prior to calling H03BBF.
The simulation itself is executed in two stages. In the first stage, a series of sample searches through the distance matrix is conducted where each proposed new state is accepted, regardless of the change in cost (delta) incurred by applying the switches, and statistics on the set of deltas are recorded. These metrics are updated after each such sample search; the number of these searches and the number of switches applied in each search is dependent on the number of cities. The final collated set of metrics for the deltas obtained by the first stage are used as control parameters for the second stage. If no single improvement in cost is found during the first stage, the algorithm is terminated.
In the second stage, as before, neighbouring states are proposed. If the resulting delta is negative or causes no change the proposal is accepted and the path updated; otherwise moves are accepted based on a probabilistic criterion, a modified version of the Metropolis–Hastings algorithm.
The acceptance of some positive deltas (increased cost) reduces the probability of a solution getting trapped at a non-optimal solution where any single switch causes an increase in cost. Initially the acceptance criteria allow for relatively large positive deltas, but as the number of proposed changes increases, the criteria become more stringent, allowing fewer positive deltas of smaller size to be accepted; this process is, within the realm of the simulated annealing algorithm, referred to as ‘cooling’. Further exploration of the system is initially encouraged by accepting non-optimal routes, but is increasingly discouraged as the process continues.
The second stage will terminate when:
  • – a solution is obtained that is deemed acceptable (as defined by supplied values);
  • – the algorithm will accept no further positive deltas and a set of proposed changes have resulted in no improvements (has cooled);
  • – a number of consecutive sets of proposed changes has resulted in no improvement.

4 References

Applegate D L, Bixby R E, Chvátal V and Cook W J (2006) The Traveling Salesman Problem: A Computational Study Princeton University Press
Cook W J (2012) In Pursuit of the Traveling Salesman Princeton University Press
Johnson D S and McGeoch L A The traveling salesman problem: A case study in local optimization Local search in combinatorial optimization (1997) 215–310
Press W H, Teukolsky S A, Vetterling W T and Flannery B P (2007) Numerical Recipes The Art of Scientific Computing (3rd Edition)
Rego C, Gamboa D, Glover F and Osterman C (2011) Traveling salesman problem heuristics: leading methods, implementations and latest advances European Journal of Operational Research 211 (3) 427–441
Reinelt G (1994) The Travelling Salesman. Computational Solutions for TSP Applications, Volume 840 of Lecture Notes in Computer Science Springer–Verlag, Berlin Heidelberg New York

5 Arguments

1:   NC – INTEGERInput
On entry: the number of cities. In the trivial cases NC=1, 2 or 3, the routine returns the optimal solution immediately with TMODE=0 (provided the relevant distance matrix entries are not negative).
Constraint: NC≥1.
2:   DM NCNC – REAL (KIND=nag_wp) arrayInput
On entry: the distance matrix; each DM ij is the effective cost or weight between nodes i and j. Only the strictly upper half of the matrix is referenced.
Constraint: DM ij≥0.0, for j=2,3,…,NC and i=1,2,…,j-1.
3:   BOUND – REAL (KIND=nag_wp)Input
On entry: a lower bound on the solution. If the optimum is unknown set BOUND to zero or a negative value; the routine will then calculate the minimum spanning tree for DM and use this as a lower bound (returned in ALG_STATS 6). If an optimal value for the cost is known then this should be used for the lower bound. A detailed discussion of relaxations for lower bounds, including the minimal spanning tree, can be found in Reinelt (1994).
4:   TARGC – REAL (KIND=nag_wp)Input
On entry: a measure of how close an approximation needs to be to the lower bound. The routine terminates when a cost is found less than or equal to BOUND+TARGC. This argument is useful when an optimal value for the cost is known and supplied in BOUND. It may be sufficient to obtain a path that is close enough (in terms of cost) to the optimal path; this allows the algorithm to terminate at that point and avoid further computation in attempting to find a better path.
If TARGC<0, TARGC=0 is assumed.
5:   PATH NC – INTEGER arrayOutput
On exit: the best path discovered by the simulation. That is, PATH contains the city indices in path order. If IFAIL≠0 on exit, PATH contains the indices 1 to NC.
6:   COST – REAL (KIND=nag_wp)Output
On exit: the cost or weight of PATH. If IFAIL≠0 on exit, COST contains the largest model real number (see X02BLF).
7:   TMODE – INTEGEROutput
On exit: the termination mode of the routine (if IFAIL≠0 on exit, TMODE is set to -1):
TMODE=0
Optimal solution found, COST=BOUND.
TMODE=1
System temperature cooled. The algorithm returns a PATH and associated COST that does not attain, nor lie within TARGC of, the BOUND. This could be a sufficiently good approximation to the optimal PATH, particularly when BOUND+TARGC lies below the optimal COST.
TMODE=2
Halted by COST falling within the desired TARGC range of the BOUND.
TMODE=3
System stalled following lack of improvement.
TMODE=4
Initial search failed to find a single improvement (the solution could be optimal).
8:   ALG_STATS 6 – REAL (KIND=nag_wp) arrayOutput
On exit: an array of metrics collected during the initial search. These could be used as a basis for future optimization. If IFAIL≠0 on exit, the elements of ALG_STATS are set to zero; the first five elements are also set to zero in the trival cases NC=1, 2 or 3.
ALG_STATS 1
Mean delta.
ALG_STATS 2
Standard deviation of deltas.
ALG_STATS 3
Cost at end of initial search phase.
ALG_STATS 4
Best cost encountered during search phase.
ALG_STATS 5
Initial system temperature. At the end of stage 1 of the algorithm, this is a function of the mean and variance of the deltas, and of the distance from best cost to the lower bound. It is a measure of the initial acceptance criteria for stage 2. The larger this value, the more iterations it will take to geometrically reduce it during stage 2 until the system is cooled (below a threshold value).
ALG_STATS 6
The lower bound used, which will be that computed internally when BOUND≤0 on input. Subsequent calls with different random states can set BOUND to the value returned in ALG_STATS 6 to avoid recomputation of the minimal spanning tree.
9:   STATE* – INTEGER arrayCommunication Array
Note: the actual argument supplied must be the array STATE supplied to the initialization routines G05KFF or G05KGF.
On entry: a valid RNG state initialized by G05KFF or G05KGF. Since the algorithm used is stochastic, a random number generator is employed; if the generator is initialized to a non-repeatable sequence (G05KGF) then different solution paths will be taken on successive runs, returning possibly different final approximate solutions.
On exit: contains updated information on the state of the generator.
10:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, NC=value.
Constraint: NC≥1.
IFAIL=2
On entry, the strictly upper triangle of DM had a negative element.
IFAIL=9
On entry, STATE vector has been corrupted or not initialized.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The routine will not perform well when the average change in cost caused by switching two cities is small relative to the cost; this can happen when many of the values in the distance matrix are relatively close to each other.
The quality of results from this routine can vary quite markedly when different initial random states are used. It is therefore advisable to compute a number of approximations using different initial random states. The best cost and path can then be taken from the set of approximations obtained. If no change in results is obtained after 10 such trials then it is unlikely that any further improvement can be made by this routine.

8 Parallelism and Performance

Running many instances of the routine in parallel with independent random number generator states can yield a set of possible solutions from which a best approximate solution may be chosen.

9 Further Comments

Memory is internally allocated for 3×NC-2 integers and NC-1 real values.
In the case of two cities that are not connected, a suitably large number should be used as the distance (cost) between them so as to deter solution paths which directly connect the two cities. Solutions which contain an artificial link (i.e., a connection with a large distance between them to indicate no actual link) may be patched, using the shortest path algorithm H03ADF.
If a city is to be visited more than once (or more than twice for the home city) then the distance matrix should contain multiple entries for that city (on rows and columns i 1,i 2,…) with zero entries for distances to itself and identical distances to other cities.

10 Example

An approximation to the best path through 21 cities in the United Kingdom and Ireland, beginning and ending in Oxford, is sought. A lower bound is calculated internally.

10.1 Program Text

Program Text (h03bbfe.f90)

10.2 Program Data

Program Data (h03bbfe.d)

10.3 Program Results

Program Results (h03bbfe.r)

H Chapter Contents
H Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


H05AAF : NAG Library, Mark 26

H Chapter Contents
H Chapter Introduction
NAG Library Manual

NAG Library Routine Document

H05AAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

Given a set of m features and a scoring mechanism for any subset of those features, H05AAF selects the best n subsets of size p using a reverse communication branch and bound algorithm.

2 Specification

SUBROUTINE H05AAF ( IREVCM, MINCR, M, IP, NBEST, DROP, LZ, Z, LA, A, BSCORE, BZ, MINCNT, GAMMA, ACC, ICOMM, LICOMM, RCOMM, LRCOMM, IFAIL)
INTEGER | IREVCM, MINCR, M, IP, NBEST, DROP, LZ, Z(M-IP), LA, A(max(NBEST,M)), BZ(M-IP,NBEST), MINCNT, ICOMM(LICOMM), LICOMM, LRCOMM, IFAIL
REAL (KIND=nag_wp) | BSCORE(max(NBEST,M)), GAMMA, ACC(2), RCOMM(LRCOMM)

3 Description

Given Ω=x i:i∈ℤ,1≤i≤m, a set of m unique features and a scoring mechanism f S defined for all S ⊆ Ω then H05AAF is designed to find S o 1 ⊆ Ω , S o 1 = p , an optimal subset of size p. Here S o 1 denotes the cardinality of S o 1, the number of elements in the set.
The definition of the optimal subset depends on the properties of the scoring mechanism, if
f Si ≤ f Sj , for all ​ Sj ⊆ Ω ​ and ​ Si ⊆ Sj (1)
then the optimal subset is defined as one of the solutions to
maximize S⊆Ω f S   subject to   S = p
else if
f Si ≥ f Sj , for all ​ Sj ⊆ Ω ​ and ​ Si ⊆ Sj (2)
then the optimal subset is defined as one of the solutions to
minimize S ⊆ Ω f S   subject to   S = p .
If neither of these properties hold then H05AAF cannot be used.
As well as returning the optimal subset, S o 1, H05AAF can return the best n solutions of size p. If S oi denotes the ith best subset, for i=1,2,…,n-1, then the i+1th best subset is defined as the solution to either
maximize S ⊆ Ω - S oj : j∈ℤ , 1≤j≤i f S   subject to   S = p
or
minimize S ⊆ Ω - S oj : j∈ℤ,1≤j≤i f S   subject to   S = p
depending on the properties of f.
The solutions are found using a branch and bound method, where each node of the tree is a subset of Ω. Assuming that (1) holds then a particular node, defined by subset Si, can be trimmed from the tree if f Si < f^S on where f^S on is the nth highest score we have observed so far for a subset of size p, i.e., our current best guess of the score for the nth best subset. In addition, because of (1) we can also drop all nodes defined by any subset Sj where Sj⊆Si, thus avoiding the need to enumerate the whole tree. Similar short cuts can be taken if (2) holds. A full description of this branch and bound algorithm can be found in Ridout (1988).
Rather than calculate the score at a given node of the tree H05AAF utilizes the fast branch and bound algorithm of Somol et al. (2004), and attempts to estimate the score where possible. For each feature, xi, two values are stored, a count ci and μ^i, an estimate of the contribution of that feature. An initial value of zero is used for both ci and μ^i. At any stage of the algorithm where both f S and f S - xi have been calculated (as opposed to estimated), the estimated contribution of the feature xi is updated to
ciμ^i + f S - f S - xj ci+1
and ci is incremented by 1, therefore at each stage μ^i is the mean contribution of xi observed so far and ci is the number of observations used to calculate that mean.
As long as ci≥k, for the user-supplied constant k, then rather than calculating f S - x i this routine estimates it using f^ S - x i = f S - γ μ^i or f^ S - γ μ^i if f S has been estimated, where γ is a user-supplied scaling factor. An estimated score is never used to trim a node or returned as the optimal score.
Setting k=0 in this routine will cause the algorithm to always calculate the scores, returning to the branch and bound algorithm of Ridout (1988). In most cases it is preferable to use the fast branch and bound algorithm, by setting k>0, unless the score function is iterative in nature, i.e., f S must have been calculated before f S - xi can be calculated.

4 References

Narendra P M and Fukunaga K (1977) A branch and bound algorithm for feature subset selection IEEE Transactions on Computers 9 917–922
Ridout M S (1988) Algorithm AS 233: An improved branch and bound algorithm for feature subset selection Journal of the Royal Statistics Society, Series C (Applied Statistics) (Volume 37) 1 139–147
Somol P, Pudil P and Kittler J (2004) Fast branch and bound algorithms for optimal feature selection IEEE Transactions on Pattern Analysis and Machine Intelligence (Volume 26) 7 900–912

5 Arguments

Note: this routine uses reverse communication. Its use involves an initial entry, intermediate exits and re-entries, and a final exit, as indicated by the argument IREVCM. Between intermediate exits and re-entries, all arguments other than BSCORE must remain unchanged.
1:   IREVCM – INTEGERInput/Output
On initial entry: must be set to 0.
On intermediate exit: IREVCM=1 and before re-entry the scores associated with LA subsets must be calculated and returned in BSCORE.
The LA subsets are constructed as follows:
DROP=1
The jth subset is constructed by dropping the features specified in the first LZ elements of Z and the single feature given in A j from the full set of features, Ω. The subset will therefore contain M-LZ-1 features.
DROP=0
The jth subset is constructed by adding the features specified in the first LZ elements of Z and the single feature specified in A j to the empty set, ∅. The subset will therefore contain LZ+1 features.
In both cases the individual features are referenced by the integers 1 to M with 1 indicating the first feature, 2 the second, etc., for some arbitrary ordering of the features. The same ordering must be used in all calls to H05AAF.
If LA=0, the score for a single subset should be returned. This subset is constructed by adding or removing only those features specified in the first LZ elements of Z.
If LZ=0, this subset will either be Ω or ∅.
The score associated with the jth subset must be returned in BSCORE j.
On intermediate re-entry: IREVCM must remain unchanged.
On final exit: IREVCM=0, and the algorithm has terminated.
Constraint: IREVCM=0 or 1.
2:   MINCR – INTEGERInput
On entry: flag indicating whether the scoring function f is increasing or decreasing.
MINCR=1
f Si ≤ f Sj , i.e., the subsets with the largest score will be selected.
MINCR=0
f Si ≥ f Sj , i.e., the subsets with the smallest score will be selected.
For all Sj⊆Ω and Si⊆Sj.
Constraint: MINCR=0 or 1.
3:   M – INTEGERInput
On entry: m, the number of features in the full feature set.
Constraint: M≥2.
4:   IP – INTEGERInput
On entry: p, the number of features in the subset of interest.
Constraint: 1≤IP≤M.
5:   NBEST – INTEGERInput
On entry: n, the maximum number of best subsets required. The actual number of subsets returned is given by LA on final exit. If on final exit LA≠NBEST then IFAIL=53 is returned.
Constraint: NBEST≥1.
6:   DROP – INTEGERInput/Output
On initial entry: DROP need not be set.
On intermediate exit: flag indicating whether the intermediate subsets should be constructed by dropping features from the full set (DROP=1) or adding features to the empty set (DROP=0). See IREVCM for details.
On intermediate re-entry: DROP must remain unchanged.
On final exit: DROP is undefined.
7:   LZ – INTEGERInput/Output
On initial entry: LZ need not be set.
On intermediate exit: the number of features stored in Z.
On intermediate re-entry: LZ must remain unchanged.
On final exit: LZ is undefined.
8:   Z M-IP – INTEGER arrayInput/Output
On initial entry: Z need not be set.
On intermediate exit: Z i, for i=1,2,…,LZ, contains the list of features which, along with those specified in A, define the subsets whose score is required. See IREVCM for additional details.
On intermediate re-entry: Z must remain unchanged.
On final exit: Z is undefined.
9:   LA – INTEGERInput/Output
On initial entry: LA need not be set.
On intermediate exit: if LA>0, the number of subsets for which a score must be returned.
If LA=0, the score for a single subset should be returned. See IREVCM for additional details.
On intermediate re-entry: LA must remain unchanged.
On final exit: the number of best subsets returned.
10:   A max NBEST,M – INTEGER arrayInput/Output
On initial entry: A need not be set.
On intermediate exit: A j, for j=1,2,…,LA, contains the list of features which, along with those specified in Z, define the subsets whose score is required. See IREVCM for additional details.
On intermediate re-entry: A must remain unchanged.
On final exit: A is undefined.
11:   BSCORE max NBEST,M – REAL (KIND=nag_wp) arrayInput/Output
On initial entry: BSCORE need not be set.
On intermediate exit: BSCORE is undefined.
On intermediate re-entry: BSCORE j must hold the score for the jth subset as described in IREVCM.
On final exit: holds the score for the LA best subsets returned in BZ.
12:   BZ M-IP NBEST – INTEGER arrayInput/Output
On initial entry: BZ need not be set.
On intermediate exit: BZ is used for storage between calls to H05AAF.
On intermediate re-entry: BZ must remain unchanged.
On final exit: the jth best subset is constructed by dropping the features specified in BZ ij, for i=1,2,…,M-IP and j=1,2,…,LA, from the set of all features, Ω. The score for the jth best subset is given in BSCORE j.
13:   MINCNT – INTEGERInput
On entry: k, the minimum number of times the effect of each feature, xi, must have been observed before f S - xi is estimated from f S as opposed to being calculated directly.
If k=0 then f S - xi is never estimated. If MINCNT<0 then k is set to 1.
14:   GAMMA – REAL (KIND=nag_wp)Input
On entry: γ, the scaling factor used when estimating scores. If GAMMA<0 then γ=1 is used.
15:   ACC 2 – REAL (KIND=nag_wp) arrayInput
On entry: a measure of the accuracy of the scoring function, f.
Letting ai = ε1 ⁢ f Si + ε2 , then when confirming whether the scoring function is strictly increasing or decreasing (as described in MINCR), or when assessing whether a node defined by subset Si can be trimmed, then any values in the range f Si ± ai are treated as being numerically equivalent.
If 0≤ACC 1≤1 then ε1=ACC 1, otherwise ε 1=0.
If ACC 2≥0 then ε2=ACC 2, otherwise ε 2=0.
In most situations setting both ε 1 and ε 2 to zero should be sufficient. Using a nonzero value, when one is not required, can significantly increase the number of subsets that need to be evaluated.
16:   ICOMM LICOMM – INTEGER arrayCommunication Array
On initial entry: ICOMM need not be set.
On intermediate exit: ICOMM is used for storage between calls to H05AAF.
On intermediate re-entry: ICOMM must remain unchanged.
On final exit: ICOMM is not defined. The first two elements, ICOMM 1 and ICOMM 2 contain the minimum required value for LICOMM and LRCOMM respectively.
17:   LICOMM – INTEGERInput
On entry: the length of the array ICOMM. If LICOMM is too small and LICOMM≥2 then IFAIL=172 is returned and the minimum value for LICOMM and LRCOMM are given by ICOMM 1 and ICOMM 2 respectively.
Constraints:
  • if MINCNT=0, LICOMM≥ 2× max NBEST,M+ M M+2+ M+1× max M-IP,1+ 27 ;
  • otherwise LICOMM≥ 2× max NBEST,M+ M M+3+ 2⁢M+1× max M-IP,1+ 25 .
18:   RCOMM LRCOMM – REAL (KIND=nag_wp) arrayCommunication Array
On initial entry: RCOMM need not be set.
On intermediate exit: RCOMM is used for storage between calls to H05AAF.
On intermediate re-entry: RCOMM must remain unchanged.
On final exit: RCOMM is not defined.
19:   LRCOMM – INTEGERInput
On entry: the length of the array RCOMM. If LRCOMM is too small and LICOMM≥2 then IFAIL=172 is returned and the minimum value for LICOMM and LRCOMM are given by ICOMM 1 and ICOMM 2 respectively.
Constraints:
  • if MINCNT=0, LRCOMM ≥ 9+ NBEST+ M× max M-IP,1 ;
  • otherwise LRCOMM ≥ 8+ M+ NBEST+ M× max M-IP,1 .
20:   IFAIL – INTEGERInput/Output
On initial entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if IFAIL≠0 on exit, the recommended value is -1. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On final exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=11
On entry, IREVCM=value.
Constraint: IREVCM=0 or 1.
IFAIL=21
On entry, MINCR=value.
Constraint: MINCR=0 or 1.
IFAIL=22
MINCR has changed between calls.
On intermediate entry, MINCR=value.
On initial entry, MINCR=value.
IFAIL=31
On entry, M=value.
Constraint: M≥2.
IFAIL=32
M has changed between calls.
On intermediate entry, M=value.
On initial entry, M=value.
IFAIL=41
On entry, IP=value and M=value.
Constraint: 1≤IP≤M.
IFAIL=42
IP has changed between calls.
On intermediate entry, IP=value.
On initial entry, IP=value.
IFAIL=51
On entry, NBEST=value.
Constraint: NBEST≥1.
IFAIL=52
NBEST has changed between calls.
On intermediate entry, NBEST=value.
On initial entry, NBEST=value.
IFAIL=53
On entry, NBEST=value.
But only value best subsets could be calculated.
IFAIL=61
DROP has changed between calls.
On intermediate entry, DROP=value.
On initial entry, DROP=value.
IFAIL=71
LZ has changed between calls.
On entry, LZ=value.
On previous exit, LZ=value.
IFAIL=91
LA has changed between calls.
On entry, LA=value.
On previous exit, LA=value.
IFAIL=111
BSCORE value=value, which is inconsistent with the score for the parent node. Score for the parent node is value.
IFAIL=131
MINCNT has changed between calls.
On intermediate entry, MINCNT=value.
On initial entry, MINCNT=value.
IFAIL=141
GAMMA has changed between calls.
On intermediate entry, GAMMA=value.
On initial entry, GAMMA=value.
IFAIL=151
ACC 1 has changed between calls.
On intermediate entry, ACC 1=value.
On initial entry, ACC 1=value.
IFAIL=152
ACC 2 has changed between calls.
On intermediate entry, ACC 2=value.
On initial entry, ACC 2=value.
IFAIL=161
ICOMM has been corrupted between calls.
IFAIL=171
On entry, LICOMM=value, LRCOMM=value.
Constraint: LICOMM≥value, LRCOMM≥value.
ICOMM is too small to return the required array sizes.
IFAIL=172
On entry, LICOMM=value, LRCOMM=value.
Constraint: LICOMM≥value, LRCOMM≥value.
The minimum required values for LICOMM and LRCOMM are returned in ICOMM 1 and ICOMM 2 respectively.
IFAIL=181
RCOMM has been corrupted between calls.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The subsets returned by H05AAF are guaranteed to be optimal up to the accuracy of your calculated scores.

8 Parallelism and Performance

H05AAF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

The maximum number of unique subsets of size p from a set of m features is N= m! m-p!p! . The efficiency of the branch and bound algorithm implemented in H05AAF comes from evaluating subsets at internal nodes of the tree, that is subsets with more than p features, and where possible trimming branches of the tree based on the scores at these internal nodes as described in Narendra and Fukunaga (1977). Because of this it is possible, in some circumstances, for more than N subsets to be evaluated. This will tend to happen when most of the features have a similar effect on the subset score.
If multiple optimal subsets exist with the same score, and NBEST is too small to return them all, then the choice of which of these optimal subsets is returned is arbitrary.

10 Example

This example finds the three linear regression models, with five variables, that have the smallest residual sums of squares when fitted to a supplied dataset. The data used in this example was simulated.

10.1 Program Text

Program Text (h05aafe.f90)

10.2 Program Data

Program Data (h05aafe.d)

10.3 Program Results

Program Results (h05aafe.r)

H Chapter Contents
H Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


H05ABF : NAG Library, Mark 26

H Chapter Contents
H Chapter Introduction
NAG Library Manual

NAG Library Routine Document

H05ABF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

Given a set of m features and a scoring mechanism for any subset of those features, H05ABF selects the best n subsets of size p using a direct communication branch and bound algorithm.

2 Specification

SUBROUTINE H05ABF ( MINCR, M, IP, NBEST, LA, BSCORE, BZ, F, MINCNT, GAMMA, ACC, IUSER, RUSER, IFAIL)
INTEGER | MINCR, M, IP, NBEST, LA, BZ(M-IP,NBEST), MINCNT, IUSER(*), IFAIL
REAL (KIND=nag_wp) | BSCORE(NBEST), GAMMA, ACC(2), RUSER(*)
EXTERNAL | F

3 Description

Given Ω=x i:i∈ℤ,1≤i≤m, a set of m unique features and a scoring mechanism f S defined for all S ⊆ Ω then H05ABF is designed to find S o 1 ⊆ Ω , S o 1 = p , an optimal subset of size p. Here S o 1 denotes the cardinality of S o 1, the number of elements in the set.
The definition of the optimal subset depends on the properties of the scoring mechanism, if
f Si ≤ f Sj , for all ​ Sj ⊆ Ω ​ and ​ Si ⊆ Sj (1)
then the optimal subset is defined as one of the solutions to
maximize S⊆Ω f S   subject to   S = p
else if
f Si ≥ f Sj , for all ​ Sj ⊆ Ω ​ and ​ Si ⊆ Sj (2)
then the optimal subset is defined as one of the solutions to
minimize S ⊆ Ω f S   subject to   S = p .
If neither of these properties hold then H05ABF cannot be used.
As well as returning the optimal subset, S o 1, H05ABF can return the best n solutions of size p. If S oi denotes the ith best subset, for i=1,2,…,n-1, then the i+1th best subset is defined as the solution to either
maximize S ⊆ Ω - S oj : j∈ℤ , 1≤j≤i f S   subject to   S = p
or
minimize S ⊆ Ω - S oj : j∈ℤ,1≤j≤i f S   subject to   S = p
depending on the properties of f.
The solutions are found using a branch and bound method, where each node of the tree is a subset of Ω. Assuming that (1) holds then a particular node, defined by subset Si, can be trimmed from the tree if f Si < f^S on where f^S on is the nth highest score we have observed so far for a subset of size p, i.e., our current best guess of the score for the nth best subset. In addition, because of (1) we can also drop all nodes defined by any subset Sj where Sj⊆Si, thus avoiding the need to enumerate the whole tree. Similar short cuts can be taken if (2) holds. A full description of this branch and bound algorithm can be found in Ridout (1988).
Rather than calculate the score at a given node of the tree H05ABF utilizes the fast branch and bound algorithm of Somol et al. (2004), and attempts to estimate the score where possible. For each feature, xi, two values are stored, a count ci and μ^i, an estimate of the contribution of that feature. An initial value of zero is used for both ci and μ^i. At any stage of the algorithm where both f S and f S - xi have been calculated (as opposed to estimated), the estimated contribution of the feature xi is updated to
ciμ^i + f S - f S - xj ci+1
and ci is incremented by 1, therefore at each stage μ^i is the mean contribution of xi observed so far and ci is the number of observations used to calculate that mean.
As long as ci≥k, for the user-supplied constant k, then rather than calculating f S - x i this routine estimates it using f^ S - x i = f S - γ μ^i or f^ S - γ μ^i if f S has been estimated, where γ is a user-supplied scaling factor. An estimated score is never used to trim a node or returned as the optimal score.
Setting k=0 in this routine will cause the algorithm to always calculate the scores, returning to the branch and bound algorithm of Ridout (1988). In most cases it is preferable to use the fast branch and bound algorithm, by setting k>0, unless the score function is iterative in nature, i.e., f S must have been calculated before f S - xi can be calculated.
H05ABF is a direct communication version of H05AAF.

4 References

Narendra P M and Fukunaga K (1977) A branch and bound algorithm for feature subset selection IEEE Transactions on Computers 9 917–922
Ridout M S (1988) Algorithm AS 233: An improved branch and bound algorithm for feature subset selection Journal of the Royal Statistics Society, Series C (Applied Statistics) (Volume 37) 1 139–147
Somol P, Pudil P and Kittler J (2004) Fast branch and bound algorithms for optimal feature selection IEEE Transactions on Pattern Analysis and Machine Intelligence (Volume 26) 7 900–912

5 Arguments

1:   MINCR – INTEGERInput
On entry: flag indicating whether the scoring function f is increasing or decreasing.
MINCR=1
f Si ≤ f Sj , i.e., the subsets with the largest score will be selected.
MINCR=0
f Si ≥ f Sj , i.e., the subsets with the smallest score will be selected.
For all Sj⊆Ω and Si⊆Sj.
Constraint: MINCR=0 or 1.
2:   M – INTEGERInput
On entry: m, the number of features in the full feature set.
Constraint: M≥2.
3:   IP – INTEGERInput
On entry: p, the number of features in the subset of interest.
Constraint: 1≤IP≤M.
4:   NBEST – INTEGERInput
On entry: n, the maximum number of best subsets required. The actual number of subsets returned is given by LA on final exit. If on final exit LA≠NBEST then IFAIL=42 is returned.
Constraint: NBEST≥1.
5:   LA – INTEGEROutput
On exit: the number of best subsets returned.
6:   BSCORE NBEST – REAL (KIND=nag_wp) arrayOutput
On exit: holds the score for the LA best subsets returned in BZ.
7:   BZ M-IP NBEST – INTEGER arrayOutput
On exit: the jth best subset is constructed by dropping the features specified in BZ ij, for i=1,2,…,M-IP and j=1,2,…,LA, from the set of all features, Ω. The score for the jth best subset is given in BSCORE j.
8:   F – SUBROUTINE, supplied by the user.External Procedure
F must evaluate the scoring function f.
The specification of F is:
SUBROUTINE F ( M, DROP, LZ, Z, LA, A, SCORE, IUSER, RUSER, INFO)
INTEGER | M, DROP, LZ, Z(LZ), LA, A(LA), IUSER(*), INFO
REAL (KIND=nag_wp) | SCORE(max(LA,1)), RUSER(*)
1:   M – INTEGERInput
On entry: m=Ω, the number of features in the full feature set.
2:   DROP – INTEGERInput
On entry: flag indicating whether the intermediate subsets should be constructed by dropping features from the full set (DROP=1) or adding features to the empty set (DROP=0). See SCORE for additional details.
3:   LZ – INTEGERInput
On entry: the number of features stored in Z.
4:   Z LZ – INTEGER arrayInput
On entry: Z i, for i=1,2,…,LZ, contains the list of features which, along with those specified in A, define the subsets whose score is required. See SCORE for additional details.
5:   LA – INTEGERInput
On entry: if LA>0, the number of subsets for which a score must be returned.
If LA=0, the score for a single subset should be returned. See SCORE for additional details.
6:   A LA – INTEGER arrayInput
On entry: A j, for j=1,2,…,LA, contains the list of features which, along with those specified in Z, define the subsets whose score is required. See SCORE for additional details.
7:   SCORE max LA,1 – REAL (KIND=nag_wp) arrayOutput
On exit: the value f Sj , for j=1,2,…,LA, the score associated with the jth subset. Sj is constructed as follows:
DROP=1
Sj is constructed by dropping the features specified in the first LZ elements of Z and the single feature given in A j from the full set of features, Ω. The subset will therefore contain M-LZ-1 features.
DROP=0
Sj is constructed by adding the features specified in the first LZ elements of Z and the single feature specified in A j to the empty set, ∅. The subset will therefore contain LZ+1 features.
In both cases the individual features are referenced by the integers 1 to M with 1 indicating the first feature, 2 the second, etc., for some arbitrary ordering of the features, chosen by you prior to calling H05ABF. For example, 1 might refer to the first variable in a particular set of data, 2 the second, etc..
If LA=0, the score for a single subset should be returned. This subset is constructed by adding or removing only those features specified in the first LZ elements of Z. If LZ=0, this subset will either be Ω or ∅.
8:   IUSER* – INTEGER arrayUser Workspace
9:   RUSER* – REAL (KIND=nag_wp) arrayUser Workspace
F is called with the arguments IUSER and RUSER as supplied to H05ABF. You are free to use the arrays IUSER and RUSER to supply information to F as an alternative to using COMMON global variables.
10:   INFO – INTEGERInput/Output
On entry: INFO=0.
On exit: set INFO to a nonzero value if you wish H05ABF to terminate with IFAIL=82.
F must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which H05ABF is called. Arguments denoted as Input must not be changed by this procedure.
9:   MINCNT – INTEGERInput
On entry: k, the minimum number of times the effect of each feature, xi, must have been observed before f S - xi is estimated from f S as opposed to being calculated directly.
If k=0 then f S - xi is never estimated. If MINCNT<0 then k is set to 1.
10:   GAMMA – REAL (KIND=nag_wp)Input
On entry: γ, the scaling factor used when estimating scores. If GAMMA<0 then γ=1 is used.
11:   ACC 2 – REAL (KIND=nag_wp) arrayInput
On entry: a measure of the accuracy of the scoring function, f.
Letting ai = ε1 ⁢ f Si + ε2 , then when confirming whether the scoring function is strictly increasing or decreasing (as described in MINCR), or when assessing whether a node defined by subset Si can be trimmed, then any values in the range f Si ± ai are treated as being numerically equivalent.
If 0≤ACC 1≤1 then ε1=ACC 1, otherwise ε 1=0.
If ACC 2≥0 then ε2=ACC 2, otherwise ε 2=0.
In most situations setting both ε 1 and ε 2 to zero should be sufficient. Using a nonzero value, when one is not required, can significantly increase the number of subsets that need to be evaluated.
12:   IUSER* – INTEGER arrayUser Workspace
13:   RUSER* – REAL (KIND=nag_wp) arrayUser Workspace
IUSER and RUSER are not used by H05ABF, but are passed directly to F and may be used to pass information to this routine as an alternative to using COMMON global variables.
14:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=11
On entry, MINCR=value.
Constraint: MINCR=0 or 1.
IFAIL=21
On entry, M=value.
Constraint: M≥2.
IFAIL=31
On entry, IP=value and M=value.
Constraint: 1≤IP≤M.
IFAIL=41
On entry, NBEST=value.
Constraint: NBEST≥1.
IFAIL=42
On entry, NBEST=value.
But only value best subsets could be calculated.
IFAIL=81
On exit from F, SCORE value=value, which is inconsistent with the score for the parent node. Score for the parent node is value.
IFAIL=82
A nonzero value for INFO has been returned: INFO=value.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The subsets returned by H05ABF are guaranteed to be optimal up to the accuracy of the calculated scores.

8 Parallelism and Performance

H05ABF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

The maximum number of unique subsets of size p from a set of m features is N= m! m-p!p! . The efficiency of the branch and bound algorithm implemented in H05ABF comes from evaluating subsets at internal nodes of the tree, that is subsets with more than p features, and where possible trimming branches of the tree based on the scores at these internal nodes as described in Narendra and Fukunaga (1977). Because of this it is possible, in some circumstances, for more than N subsets to be evaluated. This will tend to happen when most of the features have a similar effect on the subset score.
If multiple optimal subsets exist with the same score, and NBEST is too small to return them all, then the choice of which of these optimal subsets is returned is arbitrary.

10 Example

This example finds the three linear regression models, with five variables, that have the smallest residual sums of squares when fitted to a supplied dataset. The data used in this example was simulated.

10.1 Program Text

Program Text (h05abfe.f90)

10.2 Program Data

Program Data (h05abfe.d)

10.3 Program Results

Program Results (h05abfe.r)

H Chapter Contents
H Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


H Chapter Contents : NAG Library Manual, Mark 26

H Chapter Introduction

NAG Library Chapter Contents

H – Operations Research

H Chapter Introduction – a description of the Chapter and an overview of the algorithms available

Routine Name | Mark of Introduction | Purpose
H02BBF Example Text Example Data | 14 | nagf_mip_ilp_dense Integer LP problem (dense)
H02BFF Example Text Example Options | 16 | nagf_mip_ilp_mpsx Interpret MPSX data file defining IP or LP problem, optimize and print solution
H02BUF Example Text Example Options | 16 | nagf_mip_ilp_mpsx_convert Convert MPSX data file defining IP or LP problem to format required by H02BBF or E04MFF/E04MFA
H02BVF | 16 | nagf_mip_ilp_print Print IP or LP solutions with user-specified names for rows and columns
H02BZF Example Text Example Data | 15 | nagf_mip_ilp_info Integer programming solution, supplies further information on solution obtained by H02BBF
H02CBF Example Text Example Data | 19 | nagf_mip_iqp_dense Integer QP problem (dense)
H02CCF Example Text Example Options Example Data | 19 | nagf_mip_iqp_dense_optfile Read optional parameter values for H02CBF from external file
H02CDF | 19 | nagf_mip_iqp_dense_optstr Supply optional parameter values to H02CBF
H02CEF Example Text Example Data | 19 | nagf_mip_iqp_sparse Integer LP or QP problem (sparse), using E04NKF/E04NKA
H02CFF Example Text Example Options Example Data | 19 | nagf_mip_iqp_sparse_optfile Read optional parameter values for H02CEF from external file
H02CGF | 19 | nagf_mip_iqp_sparse_optstr Supply optional parameter values to H02CEF
H02DAF Example Text | 25 | nagf_mip_sqp Mixed integer nonlinear programming
H02ZKF | 25 | nagf_mip_optset Option setting routine for H02DAF
H02ZLF | 25 | nagf_mip_optget Option getting routine for H02DAF
H03ABF Example Text Example Data | 4 | nagf_mip_transportation Transportation problem, modified ‘stepping stone’ method
H03ADF Example Text Example Data | 18 | nagf_mip_shortestpath Shortest path problem, Dijkstra's algorithm
H03BBF Example Text Example Data | 25 | nagf_mip_tsp_simann Travelling Salesman Problem, simulated annealing
H05AAF Example Text Example Data | 24 | nagf_best_subset_given_size_revcomm Best n subsets of size p (reverse communication)
H05ABF Example Text Example Data | 24 | nagf_best_subset_given_size Best n subsets of size p (direct communication)
H Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


H Chapter Introduction : NAG Library, Mark 26

H Chapter Contents

NAG Library Chapter Introduction

H – Operations Research

▸▿ Contents

1 Scope of the Chapter
2 Background to the Problems
▸▿ 3 Recommendations on Choice and Use of Available Routines
3.1 Transportation Problem
3.2 Feature Selection – Best Subset Problem
4 Functionality Index
5 Auxiliary Routines Associated with Library Routine Arguments
6 Routines Withdrawn or Scheduled for Withdrawal
7 References

1 Scope of the Chapter

This chapter provides routines to solve certain integer programming, transportation and shortest path problems. Additionally ‘best subset’ routines are included.

2 Background to the Problems

General linear programming (LP) problems (see Dantzig (1963)) are of the form:
  • find x=x 1,x 2,…,xn T to maximize F x=∑j=1 n cjxj
  • subject to linear constraints which may have the forms:
    ∑j=1 n a ijxj=bi, i=1,2,…,m 1 (equality) ∑j=1 n a ijxj≤bi, i=m 1+1,…,m 2 (inequality) ∑j=1 n a ijxj≥bi, i=m 2+1,…,m (inequality) xj≥lj, j=1,2,…,n (simple bound) xj≤uj, j=1,2,…,n (simple bound)
This chapter deals with integer programming (IP) problems in which some or all the elements of the solution vector x are further constrained to be integers. For general LP problems where x takes only real (i.e., noninteger) values, refer to Chapter E04.
IP problems may or may not have a solution, which may or may not be unique.
Consider for example the following problem:
minimize 3 x 1 + 2 x 2 subject to 4 x 1 + 2 x 2≥5 2 x 2≤5 0 x 1 - 0 x 2≤2 and 0 x 1 ≥ 0,x 2≥0.
The hatched area in Figure 1 is the feasible region, the region where all the constraints are satisfied, and the points within it which have integer coordinates are circled. The lines of hatching are in fact contours of decreasing values of the objective function 3 x 1+2 x 2, and it is clear from Figure 1 that the optimum IP solution is at the point 1,1. For this problem the solution is unique.
However, there are other possible situations.
(a) There may be more than one solution; e.g., if the objective function in the above problem were changed to x 1+x 2, both 1,1 and 2,0 would be IP solutions.
(b) The feasible region may contain no points with integer coordinates, e.g., if an additional constraint
3 x 1≤2
were added to the above problem.
(c) There may be no feasible region, e.g., if an additional constraint
x 1+x 2≤ 1
were added to the above problem.
(d) The objective function may have no finite minimum within the feasible region; this means that the feasible region is unbounded in the direction of decreasing values of the objective function, e.g., if the constraints
4 x 1+2 x 2≥5,  x 1≥0,  x 2≥0,
were deleted from the above problem.
Figure 1
Algorithms for IP problems are usually based on algorithms for general LP problems, together with some procedure for constructing additional constraints which exclude noninteger solutions (see Beale (1977)).
The Branch and Bound (B&B) method is a well-known and widely used technique for solving IP problems (see Beale (1977) or Mitra (1973)). It involves subdividing the optimum solution to the original LP problem into two mutually exclusive sub-problems by branching an integer variable that currently has a fractional optimal value. Each sub-problem can now be solved as an LP problem, using the objective function of the original problem. The process of branching continues until a solution for one of the sub-problems is feasible with respect to the integer problem. In order to prove the optimality of this solution, the rest of the sub-problems in the B&B tree must also be solved. Naturally, if a better integer feasible solution is found for any sub-problem, it should replace the one at hand.
A common method for specifying IP and LP problems in general is the use of the MPSX file format (see IBM (1971)). A full description of this file format is provided in the routine document for H02BUF.
The efficiency in computations is enhanced by discarding inferior sub-problems. These are problems in the B&B search tree whose LP solutions are lower than (in the case of maximization) the best integer solution at hand.
The B&B method may also be applied to convex quadratic programming (QP) problems and nonlinear programming (NLP) problems using sequential convex QP approximations.
Routines have been introduced into this chapter to formally apply the technique to dense general QP problems and to sparse LP, QP or NLP problems. Section 2.6 in the E04 Chapter Introduction describes the virtues of having a well-scaled problem. The imposition that a variable be integer makes this more difficult and some practical common sense might be required to make the problem tractable. If a variable is expected to have a large value at the minimum, say 100000 for instance, then in practical terms it might be better to forget the integer constraint and simply round off the final answer. To do otherwise forces a high level of computation accuracy on the underlying optimiser that might be impossible to achieve.
A special type of linear programming problem is the transportation problem in which there are p×q variables y kl which represent quantities of goods to be transported from each of p sources to each of q destinations.
The problem is to minimize
∑k=1 p∑l=1 q c kly kl
where c kl is the unit cost of transporting from source k to destination l. The constraints are:
∑l=1 q y kl=Ak availabilities ∑k=1 p y kl=Bl requirements y kl≥0.
Note that the availabilities must equal the requirements:
∑k= 1 p Ak=∑l= 1 q Bl=∑k= 1 p∑l= 1 q y kl
and if all the Ak and Bl are integers, then so are the optimal y kl.
The shortest path problem is that of finding a path of minimum length between two distinct vertices ns and ne through a network. Suppose the vertices in the network are labelled by the integers 1,2,…,n. Let i,j denote an ordered pair of vertices in the network (where i is the origin vertex and j the destination vertex of the arc), x ij the amount of flow in arc i,j and d ij the length of the arc i,j. The LP formulation of the problem is thus given as
minimize  ∑∑d ijx ij subject to ​Ax=b,  0≤x≤1, (1)
where
a ij= + 1 if arc ​ j​ is directed away from vertex ​ i, -1 if arc ​ j​ is directed towards vertex ​ i, 0 otherwise
and
bi= +1 for ​i=ns, -1 for ​i=ne, 0 otherwise.
The above formulation only yields a meaningful solution if x ij=0​ or ​1; that is, arc i,j forms part of the shortest route only if x ij=1. In fact since the optimal LP solution will (in theory) always yield x ij=0​ or ​1, (1) can also be solved as an IP problem. Note that the problem may also be solved directly (and more efficiently) using a variant of Dijkstra's algorithm (see Ahuja et al. (1993)).
The travelling salesman problem is that of finding a minimum distance route round a given set of cities. In the classical travelling salesman problem the salesperson must visit each city only once before returning to his or her city of origin. It can be formulated as an IP problem in a number of ways. One such formulation is described in Williams (1993). Such IP problems could be solved directly by a mixed integer nonlinear programming solver; however, there are currently no routines in the Library that directly solve such IP problems. However, an acceptable solution to symmetric distance problems may be sought using the probabilistic optimization method known as simulated annealing for which a routine is available. Asymmetric problems can be tackled by the introduction of shadow cities with zero distance between an original city and its shadow. Incomplete problems, where bidirectional travel between each pair of cities is not possible, can be tackled by attributing very large distances to unavailable journeys. For example, a salesperson might not mind backtracking through a previously visited city if this produced the shortest route. This problem is known as the practical travelling salesman problem.
The best n subsets problem assumes a scoring mechanism and a set of m features. The problem is one of choosing the best n subsets of size p. It is addressed by two routines in this chapter. The first of these uses reverse communication; the second direct communication (see Section 3.3.3 in How to Use the NAG Library and its Documentation for a description of the difference between these two conventions).

3 Recommendations on Choice and Use of Available Routines

H02BBF solves dense integer programming problems using a branch and bound method.
H02BFF solves dense integer or linear programming problems defined by a MPSX data file.
H02BUF converts an MPSX data file defining an integer or a linear programming problem to the form required by E04MFF/E04MFA or H02BBF.
H02BVF prints the solution to an integer or a linear programming problem using specified names for rows and columns.
H02BZF supplies further information on the optimum solution obtained by H02BBF.
H02CBF solves dense integer general quadratic programming problems.
H02CCF reads optional parameter values for H02CBF from external file.
H02CDF supplies optional parameter values to H02CBF.
H02CEF solves sparse integer linear programming or quadratic programming problems.
H02CFF reads optional parameter values for H02CEF from external file.
H02CGF supplies optional parameter values to H02CEF.
H03ABF solves transportation problems. It uses integer arithmetic throughout and so produces exact results. On a few machines, however, there is a risk of integer overflow without warning, so the integer values in the data should be kept as small as possible by dividing out any common factors from the coefficients of the constraint or objective functions.
H03ADF solves shortest path problems using Dijkstra's algorithm.
H03BBF is a (symmetric) classical travelling salesman problem.
H02BBF, H02BFF and H03ABF treat all matrices as dense and hence are not intended for large sparse problems. For solving large sparse LP problems, use E04NQF or E04UGF/E04UGA.

3.1 Transportation Problem

H03ABF solves transportation problems. It uses integer arithmetic throughout and so produces exact results. On a few machines, however, there is a risk of integer overflow without warning, so the integer values in the data should be kept as small as possible by dividing out any common factors from the coefficients of the constraint or objective functions.

3.2 Feature Selection – Best Subset Problem

H05AAF selects the best n subsets of size p using a reverse communication branch and bound algorithm.
H05ABF selects the best n subsets of size p using a direct communication branch and bound algorithm.

4 Functionality Index

Convert data to arrays for use with H02BBF or E04MFF/E04MFA H02BUF
Feature selection,
best subset,
Given size,
direct communication H05ABF
reverse communication H05AAF
Integer programming problem (dense):
print solution with specified names H02BVF
solve LP problem using branch and bound method H02BBF
solve nonlinear problem SQP H02DAF
solve QP problem using branch and bound method H02CBF
supply further information on the solution obtained from H02BBF H02BZF
Integer programming problem (sparse):
solve LP or QP problem using branch and bound method H02CEF
MPSX data input, defining IP or LP problem,
interpret data, optimize and print solution H02BFF
Read optional parameter values from external file for H02CBF H02CCF
Read optional parameter values from external file for H02CEF H02CFF
Service routines,
optional parameter getting routine for use with H02DAF H02ZLF
optional parameter setting routine for use with H02DAF H02ZKF
Shortest path, through directed or undirected network H03ADF
Supply optional parameter values to H02CBF H02CDF
Supply optional parameter values to H02CEF H02CGF
Transportation problem H03ABF
Travelling Salesman Problem, simulated annealing H03BBF

5 Auxiliary Routines Associated with Library Routine Arguments

H02CBU | nagf_mip_iqp_dense_dummy_monit See the description of the argument MONIT in H02CBF.
H02CEY | nagf_mip_iqp_sparse_dummy_monit See the description of the argument MONIT in H02CEF.
H02DDM | nagf_mip_sqp_dummy_confun See the description of the argument CONFUN in H02DAF.

6 Routines Withdrawn or Scheduled for Withdrawal

None.

7 References

Ahuja R K, Magnanti T L and Orlin J B (1993) Network Flows: Theory, Algorithms and Applications Prentice–Hall
Beale E M (1977) Integer programming The State of the Art in Numerical Analysis (ed D A H Jacobs) Academic Press
Dantzig G B (1963) Linear Programming and Extensions Princeton University Press
IBM (1971) MPSX – Mathematical programming system Program Number 5734 XM4 IBM Trade Corporation, New York
Mitra G (1973) Investigation of some branch and bound strategies for the solution of mixed integer linear programs Math. Programming 4 155–170
Williams H P (1993) Model Building in Mathematical Programming (3rd Edition) Wiley
H Chapter Contents
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


M01CAF : NAG Library, Mark 26

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

M01CAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

M01CAF rearranges a vector of real numbers into ascending or descending order.

2 Specification

SUBROUTINE M01CAF ( RV, M1, M2, ORDER, IFAIL)
INTEGER | M1, M2, IFAIL
REAL (KIND=nag_wp) | RV(M2)
CHARACTER(1) | ORDER

3 Description

M01CAF is based on Singleton's implementation of the ‘median-of-three’ Quicksort algorithm (see Singleton (1969)), but with two additional modifications. First, small subfiles are sorted by an insertion sort on a separate final pass (see Sedgewick (1978)). Second, if a subfile is partitioned into two very unbalanced subfiles, the larger of them is flagged for special treatment: before it is partitioned, its end points are swapped with two random points within it; this makes the worst case behaviour extremely unlikely.

4 References

Sedgewick R (1978) Implementing Quicksort programs Comm. ACM 21 847–857
Singleton R C (1969) An efficient algorithm for sorting with minimal storage: Algorithm 347 Comm. ACM 12 185–187

5 Arguments

1:   RV M2 – REAL (KIND=nag_wp) arrayInput/Output
On entry: elements M1 to M2 of RV must contain real values to be sorted.
On exit: these values are rearranged into sorted order.
2:   M1 – INTEGERInput
On entry: the index of the first element of RV to be sorted.
Constraint: M1>0.
3:   M2 – INTEGERInput
On entry: the index of the last element of RV to be sorted.
Constraint: M2≥M1.
4:   ORDER – CHARACTER(1)Input
On entry: if ORDER='A', the values will be sorted into ascending (i.e., nondecreasing) order.
If ORDER='D', into descending order.
Constraint: ORDER='A' or 'D'.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | M2<1,
or | M1<1,
or | M1>M2.
IFAIL=2
On entry, ORDER is not 'A' or 'D'.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

M01CAF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

The average time taken by M01CAF is approximately proportional to n×log n, where n=M2-M1+1. The worst case time is proportional to n 2 but this is extremely unlikely to occur.

10 Example

This example reads a list of real numbers and sorts them into ascending order.

10.1 Program Text

Program Text (m01cafe.f90)

10.2 Program Data

Program Data (m01cafe.d)

10.3 Program Results

Program Results (m01cafe.r)

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


M01CBF : NAG Library, Mark 26

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

M01CBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

M01CBF rearranges a vector of integer numbers into ascending or descending order.

2 Specification

SUBROUTINE M01CBF ( IV, M1, M2, ORDER, IFAIL)
INTEGER | IV(M2), M1, M2, IFAIL
CHARACTER(1) | ORDER

3 Description

M01CBF is based on Singleton's implementation of the ‘median-of-three’ Quicksort algorithm (see Singleton (1969)), but with two additional modifications. First, small subfiles are sorted by an insertion sort on a separate final pass (see Sedgewick (1978)) Second, if a subfile is partitioned into two very unbalanced subfiles, the larger of them is flagged for special treatment: before it is partitioned, its end points are swapped with two random points within it; this makes the worst case behaviour extremely unlikely.

4 References

Sedgewick R (1978) Implementing Quicksort programs Comm. ACM 21 847–857
Singleton R C (1969) An efficient algorithm for sorting with minimal storage: Algorithm 347 Comm. ACM 12 185–187

5 Arguments

1:   IV M2 – INTEGER arrayInput/Output
On entry: elements M1 to M2 of IV must contain integer values to be sorted.
On exit: these values are rearranged into sorted order.
2:   M1 – INTEGERInput
On entry: the index of the first element of IV to be sorted.
Constraint: M1>0.
3:   M2 – INTEGERInput
On entry: the index of the last element of IV to be sorted.
Constraint: M2≥M1.
4:   ORDER – CHARACTER(1)Input
On entry: if ORDER='A', the values will be sorted into ascending (i.e., nondecreasing) order.
If ORDER='D', into descending order.
Constraint: ORDER='A' or 'D'.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | M2<1,
or | M1<1,
or | M1>M2.
IFAIL=2
On entry, ORDER is not 'A' or 'D'.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

M01CBF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

The average time taken by the routine is approximately proportional to n×log n, where n=M2-M1+1. The worst case time is proportional to n 2 but this is extremely unlikely to occur.

10 Example

This example reads a list of integers and sorts them into descending order.

10.1 Program Text

Program Text (m01cbfe.f90)

10.2 Program Data

Program Data (m01cbfe.d)

10.3 Program Results

Program Results (m01cbfe.r)

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


M01CCF : NAG Library, Mark 26

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

M01CCF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

M01CCF rearranges a vector of character data so that a specified substring is in ASCII or reverse ASCII order.

2 Specification

SUBROUTINE M01CCF ( CH, M1, M2, L1, L2, ORDER, IFAIL)
INTEGER | M1, M2, L1, L2, IFAIL
CHARACTER(*) | CH(M2)
CHARACTER(1) | ORDER

3 Description

M01CCF is based on Singleton's implementation of the ‘median-of-three’ Quicksort algorithm (see Singleton (1969)), but with two additional modifications. First, small subfiles are sorted by an insertion sort on a separate final pass (see Sedgewick (1978)) Second, if a subfile is partitioned into two very unbalanced subfiles, the larger of them is flagged for special treatment: before it is partitioned, its end points are swapped with two random points within it; this makes the worst case behaviour extremely unlikely.
Only the substring (L1:L2) of each element of the array CH is used to determine the sorted order, but the entire elements are rearranged into sorted order.

4 References

Sedgewick R (1978) Implementing Quicksort programs Comm. ACM 21 847–857
Singleton R C (1969) An efficient algorithm for sorting with minimal storage: Algorithm 347 Comm. ACM 12 185–187

5 Arguments

1:   CH M2 – CHARACTER(*) arrayInput/Output
On entry: elements M1 to M2 of CH must contain character data to be sorted.
Constraint: the length of each element of CH must not exceed 255.
On exit: these values are rearranged into sorted order.
2:   M1 – INTEGERInput
On entry: the index of the first element of CH to be sorted.
Constraint: M1>0.
3:   M2 – INTEGERInput
On entry: the index of the last element of CH to be sorted.
Constraint: M2≥M1.
4:   L1 – INTEGERInput
5:   L2 – INTEGERInput
On entry: only the substring (L1:L2) of each element of CH is to be used in determining the sorted order.
Constraint: 0<L1≤L2≤LEN CH 1.
6:   ORDER – CHARACTER(1)Input
On entry: if ORDER='A', the values will be sorted into ASCII order.
If ORDER='R', into reverse ASCII order.
Constraint: ORDER='A' or 'R'.
7:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | M2<1,
or | M1<1,
or | M1>M2,
or | L2<1,
or | L1<1,
or | L1>L2,
or | L2>LEN CH 1.
IFAIL=2
On entry, ORDER is not 'A' or 'R'.
IFAIL=3
On entry, the length of each element of CH exceeds 255.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

M01CCF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

The average time taken by the routine is approximately proportional to n×log n, where n=M2-M1+1. The worst case time is proportional to n 2, but this is extremely unlikely to occur.
The routine relies on the Fortran intrinsic functions LLT and LGT to order characters according to the ASCII collating sequence.

10 Example

This example reads a file of 12-character records, and sorts them into reverse ASCII order on characters 7 to 12.

10.1 Program Text

Program Text (m01ccfe.f90)

10.2 Program Data

Program Data (m01ccfe.d)

10.3 Program Results

Program Results (m01ccfe.r)

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


M01 Chapter Contents : NAG Library Manual, Mark 26

M01 Chapter Introduction

NAG Library Chapter Contents

M01 – Sorting and Searching

M01 Chapter Introduction – a description of the Chapter and an overview of the algorithms available

Routine Name | Mark of Introduction | Purpose
M01CAF Example Text Example Data | 12 | nagf_sort_realvec_sort Sort a vector, real numbers
M01CBF Example Text Example Data | 12 | nagf_sort_intvec_sort Sort a vector, integer numbers
M01CCF Example Text Example Data | 12 | nagf_sort_charvec_sort Sort a vector, character data
M01DAF Example Text Example Data | 12 | nagf_sort_realvec_rank Rank a vector, real numbers
M01DBF Example Text Example Data | 12 | nagf_sort_intvec_rank Rank a vector, integer numbers
M01DCF Example Text Example Data | 12 | nagf_sort_charvec_rank Rank a vector, character data
M01DEF Example Text Example Data | 12 | nagf_sort_realmat_rank_rows Rank rows of a matrix, real numbers
M01DFF Example Text Example Data | 12 | nagf_sort_intmat_rank_rows Rank rows of a matrix, integer numbers
M01DJF Example Text Example Data | 12 | nagf_sort_realmat_rank_columns Rank columns of a matrix, real numbers
M01DKF Example Text Example Data | 12 | nagf_sort_intmat_rank_columns Rank columns of a matrix, integer numbers
M01DZF Example Text Example Data | 12 | nagf_sort_arbitrary_rank Rank arbitrary data
M01EAF Example Text Example Data | 12 | nagf_sort_realvec_rank_rearrange Rearrange a vector according to given ranks, real numbers
M01EBF Example Text Example Data | 12 | nagf_sort_intvec_rank_rearrange Rearrange a vector according to given ranks, integer numbers
M01ECF Example Text Example Data | 12 | nagf_sort_charvec_rank_rearrange Rearrange a vector according to given ranks, character data
M01EDF Example Text Example Data | 19 | nagf_sort_cmplxvec_rank_rearrange Rearrange a vector according to given ranks, complex numbers
M01NAF Example Text Example Data | 22 | nagf_sort_realvec_search Binary search in set of real numbers
M01NBF Example Text Example Data | 22 | nagf_sort_intvec_search Binary search in set of integer numbers
M01NCF Example Text Example Data | 22 | nagf_sort_charvec_search Binary search in set of character data
M01ZAF Example Text Example Data | 12 | nagf_sort_permute_invert Invert a permutation
M01ZBF Example Text Example Data | 12 | nagf_sort_permute_check Check validity of a permutation
M01ZCF Example Text Example Data | 12 | nagf_sort_permute_decompose Decompose a permutation into cycles
M01 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


M01DAF : NAG Library, Mark 26

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

M01DAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

M01DAF ranks a vector of real numbers in ascending or descending order.

2 Specification

SUBROUTINE M01DAF ( RV, M1, M2, ORDER, IRANK, IFAIL)
INTEGER | M1, M2, IRANK(M2), IFAIL
REAL (KIND=nag_wp) | RV(M2)
CHARACTER(1) | ORDER

3 Description

M01DAF uses a variant of list-merging, as described on pages 165–166 in Knuth (1973). The routine takes advantage of natural ordering in the data, and uses a simple list insertion in a preparatory pass to generate ordered lists of length at least 10. The ranking is stable: equal elements preserve their ordering in the input data.

4 References

Knuth D E (1973) The Art of Computer Programming (Volume 3) (2nd Edition) Addison–Wesley

5 Arguments

1:   RV M2 – REAL (KIND=nag_wp) arrayInput
On entry: elements M1 to M2 of RV must contain real values to be ranked.
2:   M1 – INTEGERInput
On entry: the index of the first element of RV to be ranked.
Constraint: M1>0.
3:   M2 – INTEGERInput
On entry: the index of the last element of RV to be ranked.
Constraint: M2≥M1.
4:   ORDER – CHARACTER(1)Input
On entry: if ORDER='A', the values will be ranked in ascending (i.e., nondecreasing) order.
If ORDER='D', into descending order.
Constraint: ORDER='A' or 'D'.
5:   IRANK M2 – INTEGER arrayOutput
On exit: elements M1 to M2 of IRANK contain the ranks of the corresponding elements of RV. Note that the ranks are in the range M1 to M2: thus, if RV i is the first element in the rank order, IRANK i is set to M1.
6:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | M2<1,
or | M1<1,
or | M1>M2.
IFAIL=2
On entry, ORDER is not 'A' or 'D'.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

M01DAF is not threaded in any implementation.

9 Further Comments

The average time taken by the routine is approximately proportional to n×log n, where n=M2-M1+1.

10 Example

This example reads a list of real numbers and ranks them in ascending order.

10.1 Program Text

Program Text (m01dafe.f90)

10.2 Program Data

Program Data (m01dafe.d)

10.3 Program Results

Program Results (m01dafe.r)

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


M01DBF : NAG Library, Mark 26

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

M01DBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

M01DBF ranks a vector of integer numbers in ascending or descending order.

2 Specification

SUBROUTINE M01DBF ( IV, M1, M2, ORDER, IRANK, IFAIL)
INTEGER | IV(M2), M1, M2, IRANK(M2), IFAIL
CHARACTER(1) | ORDER

3 Description

M01DBF uses a variant of list-merging, as described on pages 165–166 in Knuth (1973). The routine takes advantage of natural ordering in the data, and uses a simple list insertion in a preparatory pass to generate ordered lists of length at least 10. The ranking is stable: equal elements preserve their ordering in the input data.

4 References

Knuth D E (1973) The Art of Computer Programming (Volume 3) (2nd Edition) Addison–Wesley

5 Arguments

1:   IV M2 – INTEGER arrayInput
On entry: elements M1 to M2 of IV must contain integer values to be ranked.
2:   M1 – INTEGERInput
On entry: the index of the first element of IV to be ranked.
Constraint: M1>0.
3:   M2 – INTEGERInput
On entry: M2 must specify the index of the last element of IV to be ranked.
Constraint: M2≥M1.
4:   ORDER – CHARACTER(1)Input
On entry: if ORDER='A', the values will be ranked in ascending (i.e., nondecreasing) order.
If ORDER='D', into descending order.
Constraint: ORDER='A' or 'D'.
5:   IRANK M2 – INTEGER arrayOutput
On exit: elements M1 to M2 of IRANK contain the ranks of the corresponding elements of IV. Note that the ranks are in the range M1 to M2: thus, if IV i is the first element in the rank order, IRANK i is set to M1.
6:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | M2<1,
or | M1<1,
or | M1>M2.
IFAIL=2
On entry, ORDER is not 'A' or 'D'.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

M01DBF is not threaded in any implementation.

9 Further Comments

The average time taken by the routine is approximately proportional to n×log n, where n=M2-M1+1.

10 Example

This example reads a list of integers and ranks them in descending order.

10.1 Program Text

Program Text (m01dbfe.f90)

10.2 Program Data

Program Data (m01dbfe.d)

10.3 Program Results

Program Results (m01dbfe.r)

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


M01DCF : NAG Library, Mark 26

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

M01DCF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

M01DCF ranks a vector of character data in ASCII or reverse ASCII order of a specified substring.

2 Specification

SUBROUTINE M01DCF ( CH, M1, M2, L1, L2, ORDER, IRANK, IFAIL)
INTEGER | M1, M2, L1, L2, IRANK(M2), IFAIL
CHARACTER(*) | CH(M2)
CHARACTER(1) | ORDER

3 Description

M01DCF uses a variant of list-merging, as described on pages 165–166 in Knuth (1973). The routine takes advantage of natural ordering in the data, and uses a simple list insertion in a preparatory pass to generate ordered lists of length at least 10. The ranking is stable: equal elements preserve their ordering in the input data.
Only the substring (L1:L2) of each element of the array CH is used to determine the rank order.

4 References

Knuth D E (1973) The Art of Computer Programming (Volume 3) (2nd Edition) Addison–Wesley

5 Arguments

1:   CH M2 – CHARACTER(*) arrayInput
On entry: elements M1 to M2 of CH must contain character data to be ranked.
Constraint: the length of each element of CH must not exceed 255.
2:   M1 – INTEGERInput
On entry: the index of the first element of CH to be ranked.
Constraint: M1>0.
3:   M2 – INTEGERInput
On entry: the index of the last element of CH to be ranked.
Constraint: M2≥M1.
4:   L1 – INTEGERInput
5:   L2 – INTEGERInput
On entry: only the substring (L1:L2) of each element of CH is to be used in determining the rank order.
Constraint: 0<L1≤L2≤LEN CH 1.
6:   ORDER – CHARACTER(1)Input
On entry: if ORDER='A', the values will be ranked in ASCII order.
If ORDER='R', in reverse ASCII order.
Constraint: ORDER='A' or 'R'.
7:   IRANK M2 – INTEGER arrayOutput
On exit: elements M1 to M2 of IRANK contain the ranks of the corresponding elements of CH. Note that the ranks are in the range M1 to M2: thus, if CH i is the first element in the rank order, IRANK i is set to M1.
8:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | M2<1,
or | M1<1,
or | M1>M2,
or | L2<1,
or | L1<1,
or | L1>L2,
or | L2>LEN CH 1.
IFAIL=2
On entry, ORDER is not 'A' or 'R'.
IFAIL=3
On entry, the length of each element of CH exceeds 255.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

M01DCF is not threaded in any implementation.

9 Further Comments

The average time taken by the routine is approximately proportional to n×log n, where n=M2-M1+1.
The routine relies on the Fortran intrinsic functions LLT and LGT to order characters according to the ASCII collating sequence.

10 Example

This example reads a file of 12-character records, and ranks them in reverse ASCII order on characters 7 to 12.

10.1 Program Text

Program Text (m01dcfe.f90)

10.2 Program Data

Program Data (m01dcfe.d)

10.3 Program Results

Program Results (m01dcfe.r)

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


M01DEF : NAG Library, Mark 26

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

M01DEF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

M01DEF ranks the rows of a matrix of real numbers in ascending or descending order.

2 Specification

SUBROUTINE M01DEF ( RM, LDM, M1, M2, N1, N2, ORDER, IRANK, IFAIL)
INTEGER | LDM, M1, M2, N1, N2, IRANK(M2), IFAIL
REAL (KIND=nag_wp) | RM(LDM,N2)
CHARACTER(1) | ORDER

3 Description

M01DEF ranks rows M1 to M2 of a matrix, using the data in columns N1 to N2 of those rows. The ordering is determined by first ranking the data in column N1, then ranking any tied rows according to the data in column N1+1, and so on up to column N2.
M01DEF uses a variant of list-merging, as described on pages 165–166 in Knuth (1973). The routine takes advantage of natural ordering in the data, and uses a simple list insertion in a preparatory pass to generate ordered lists of length at least 10. The ranking is stable: equal rows preserve their ordering in the input data.

4 References

Knuth D E (1973) The Art of Computer Programming (Volume 3) (2nd Edition) Addison–Wesley

5 Arguments

1:   RM LDMN2 – REAL (KIND=nag_wp) arrayInput
On entry: columns N1 to N2 of rows M1 to M2 of RM must contain real data to be ranked.
2:   LDM – INTEGERInput
On entry: the first dimension of the array RM as declared in the (sub)program from which M01DEF is called.
Constraint: LDM≥M2.
3:   M1 – INTEGERInput
On entry: the index of the first row of RM to be ranked.
Constraint: M1>0.
4:   M2 – INTEGERInput
On entry: the index of the last row of RM to be ranked.
Constraint: M2≥M1.
5:   N1 – INTEGERInput
On entry: the index of the first column of RM to be used.
Constraint: N1>0.
6:   N2 – INTEGERInput
On entry: the index of the last column of RM to be used.
Constraint: N2≥N1.
7:   ORDER – CHARACTER(1)Input
On entry: if ORDER='A', the rows will be ranked in ascending (i.e., nondecreasing) order.
If ORDER='D', into descending order.
Constraint: ORDER='A' or 'D'.
8:   IRANK M2 – INTEGER arrayOutput
On exit: elements M1 to M2 of IRANK contain the ranks of the corresponding rows of RM. Note that the ranks are in the range M1 to M2: thus, if the ith row of RM is the first in the rank order, IRANK i is set to M1.
9:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | M2<1,
or | N2<1,
or | M1<1,
or | M1>M2,
or | N1<1,
or | N1>N2,
or | LDM<M2.
IFAIL=2
On entry, ORDER is not 'A' or 'D'.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

M01DEF is not threaded in any implementation.

9 Further Comments

The average time taken by the routine is approximately proportional to n×log n, where n=M2-M1+1.

10 Example

This example reads a matrix of real numbers and ranks the rows in ascending order.

10.1 Program Text

Program Text (m01defe.f90)

10.2 Program Data

Program Data (m01defe.d)

10.3 Program Results

Program Results (m01defe.r)

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


M01DFF : NAG Library, Mark 26

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

M01DFF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

M01DFF ranks the rows of a matrix of integer numbers in ascending or descending order.

2 Specification

SUBROUTINE M01DFF ( IM, LDM, M1, M2, N1, N2, ORDER, IRANK, IFAIL)
INTEGER | IM(LDM,N2), LDM, M1, M2, N1, N2, IRANK(M2), IFAIL
CHARACTER(1) | ORDER

3 Description

M01DFF ranks rows M1 to M2 of a matrix, using the data in columns N1 to N2 of those rows. The ordering is determined by first ranking the data in column N1, then ranking any tied rows according to the data in column N1+1, and so on up to column N2.
M01DFF uses a variant of list-merging, as described on pages 165–166 in Knuth (1973). The routine takes advantage of natural ordering in the data, and uses a simple list insertion in a preparatory pass to generate ordered lists of length at least 10. The ranking is stable: equal rows preserve their ordering in the input data.

4 References

Knuth D E (1973) The Art of Computer Programming (Volume 3) (2nd Edition) Addison–Wesley

5 Arguments

1:   IM LDMN2 – INTEGER arrayInput
On entry: columns N1 to N2 of rows M1 to M2 of IM must contain integer data to be ranked.
2:   LDM – INTEGERInput
On entry: the first dimension of the array IM as declared in the (sub)program from which M01DFF is called.
Constraint: LDM≥M2.
3:   M1 – INTEGERInput
On entry: the index of the first row of IM to be ranked.
Constraint: M1>0.
4:   M2 – INTEGERInput
On entry: the index of the last row of IM to be ranked.
Constraint: M2≥M1.
5:   N1 – INTEGERInput
On entry: the index of the first column of IM to be used.
Constraint: N1>0.
6:   N2 – INTEGERInput
On entry: the index of the last column of IM to be used.
Constraint: N2≥N1.
7:   ORDER – CHARACTER(1)Input
On entry: if ORDER='A', the rows will be ranked in ascending (i.e., nondecreasing) order.
If ORDER='D', into descending order.
Constraint: ORDER='A' or 'D'.
8:   IRANK M2 – INTEGER arrayOutput
On exit: elements M1 to M2 of IRANK contain the ranks of the corresponding rows of IM. Note that the ranks are in the range M1 to M2: thus, if the ith row of IM is the first in the rank order, IRANK i is set to M1.
9:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | M2<1,
or | N2<1,
or | M1<1,
or | M1>M2,
or | N1<1,
or | N1>N2,
or | LDM<M2.
IFAIL=2
On entry, ORDER is not 'A' or 'D'.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

M01DFF is not threaded in any implementation.

9 Further Comments

The average time taken by the routine is approximately proportional to n×log n, where n=M2-M1+1.

10 Example

This example reads a matrix of integers and ranks the rows in descending order.

10.1 Program Text

Program Text (m01dffe.f90)

10.2 Program Data

Program Data (m01dffe.d)

10.3 Program Results

Program Results (m01dffe.r)

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


M01DJF : NAG Library, Mark 26

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

M01DJF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

M01DJF ranks the columns of a matrix of real numbers in ascending or descending order.

2 Specification

SUBROUTINE M01DJF ( RM, LDM, M1, M2, N1, N2, ORDER, IRANK, IFAIL)
INTEGER | LDM, M1, M2, N1, N2, IRANK(N2), IFAIL
REAL (KIND=nag_wp) | RM(LDM,N2)
CHARACTER(1) | ORDER

3 Description

M01DJF ranks columns N1 to N2 of a matrix, using the data in rows M1 to M2 of those columns. The ordering is determined by first ranking the data in row M1, then ranking any tied columns according to the data in row M1+1, and so on up to row M2.
M01DJF uses a variant of list-merging, as described on pages 165–166 in Knuth (1973). The routine takes advantage of natural ordering in the data, and uses a simple list insertion in a preparatory pass to generate ordered lists of length at least 10. The ranking is stable: equal columns preserve their ordering in the input data.

4 References

Knuth D E (1973) The Art of Computer Programming (Volume 3) (2nd Edition) Addison–Wesley

5 Arguments

1:   RM LDMN2 – REAL (KIND=nag_wp) arrayInput
On entry: rows M1 to M2 of columns N1 to N2 of RM must contain real data to be ranked.
2:   LDM – INTEGERInput
On entry: the first dimension of the array RM as declared in the (sub)program from which M01DJF is called.
Constraint: LDM≥M2.
3:   M1 – INTEGERInput
On entry: the index of the first row of RM to be used.
Constraint: M1>0.
4:   M2 – INTEGERInput
On entry: the index of the last row of RM to be used.
Constraint: M2≥M1.
5:   N1 – INTEGERInput
On entry: the index of the first column of RM to be ranked.
Constraint: N1>0.
6:   N2 – INTEGERInput
On entry: the index of the last column of RM to be ranked.
Constraint: N2≥N1.
7:   ORDER – CHARACTER(1)Input
On entry: if ORDER='A', the columns will be ranked in ascending (i.e., nondecreasing) order.
If ORDER='D', into descending order.
Constraint: ORDER='A' or 'D'.
8:   IRANK N2 – INTEGER arrayOutput
On exit: elements N1 to N2 of IRANK contain the ranks of the corresponding columns of RM. Note that the ranks are in the range N1 to N2: thus, if the ith column of RM is the first in the rank order, IRANK i is set to N1.
9:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | M2<1,
or | N2<1,
or | M1<1,
or | M1>M2,
or | N1<1,
or | N1>N2,
or | LDM<M2.
IFAIL=2
On entry, ORDER is not 'A' or 'D'.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

M01DJF is not threaded in any implementation.

9 Further Comments

The average time taken by the routine is approximately proportional to n×log n, where n=N2-N1+1.

10 Example

This example reads a matrix of real numbers and ranks the columns in ascending order.

10.1 Program Text

Program Text (m01djfe.f90)

10.2 Program Data

Program Data (m01djfe.d)

10.3 Program Results

Program Results (m01djfe.r)

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


M01DKF : NAG Library, Mark 26

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

M01DKF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

M01DKF ranks the columns of a matrix of integer numbers in ascending or descending order.

2 Specification

SUBROUTINE M01DKF ( IM, LDM, M1, M2, N1, N2, ORDER, IRANK, IFAIL)
INTEGER | IM(LDM,N2), LDM, M1, M2, N1, N2, IRANK(N2), IFAIL
CHARACTER(1) | ORDER

3 Description

M01DKF ranks columns N1 to N2 of a matrix, using the data in rows M1 to M2 of those columns. The ordering is determined by first ranking the data in row M1, then ranking any tied columns according to the data in row M1+1, and so on up to row M2.
M01DKF uses a variant of list-merging, as described on pages 165–166 in Knuth (1973). The routine takes advantage of natural ordering in the data, and uses a simple list insertion in a preparatory pass to generate ordered lists of length at least 10. The ranking is stable: equal columns preserve their ordering in the input data.

4 References

Knuth D E (1973) The Art of Computer Programming (Volume 3) (2nd Edition) Addison–Wesley

5 Arguments

1:   IM LDMN2 – INTEGER arrayInput
On entry: rows M1 to M2 of columns N1 to N2 of IM must contain integer data to be ranked.
2:   LDM – INTEGERInput
On entry: the first dimension of the array IM as declared in the (sub)program from which M01DKF is called.
Constraint: LDM≥M2.
3:   M1 – INTEGERInput
On entry: the index of the first row of IM to be used.
Constraint: M1>0.
4:   M2 – INTEGERInput
On entry: the index of the last row of IM to be used.
Constraint: M2≥M1.
5:   N1 – INTEGERInput
On entry: the index of the first column of IM to be ranked.
Constraint: N1>0.
6:   N2 – INTEGERInput
On entry: the index of the last column of IM to be ranked.
Constraint: N2≥N1.
7:   ORDER – CHARACTER(1)Input
On entry: if ORDER='A', the columns will be ranked in ascending (i.e., nondecreasing) order.
If ORDER='D', into descending order.
Constraint: ORDER='A' or 'D'.
8:   IRANK N2 – INTEGER arrayOutput
On exit: elements N1 to N2 of IRANK contain the ranks of the corresponding columns of IM. Note that the ranks are in the range N1 to N2: thus, if the ith column of IM is the first in the rank order, IRANK i is set to N1.
9:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | M2<1,
or | N2<1,
or | M1<1,
or | M1>M2,
or | N1<1,
or | N1>N2,
or | LDM<M2.
IFAIL=2
On entry, ORDER is not 'A' or 'D'.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

M01DKF is not threaded in any implementation.

9 Further Comments

The average time taken by the routine is approximately proportional to n×log n, where n=N2-N1+1.

10 Example

This example reads a matrix of integers and ranks the columns in descending order.

10.1 Program Text

Program Text (m01dkfe.f90)

10.2 Program Data

Program Data (m01dkfe.d)

10.3 Program Results

Program Results (m01dkfe.r)

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


M01DZF : NAG Library, Mark 26

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

M01DZF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

M01DZF ranks arbitrary data according to a user-supplied comparison routine.

2 Specification

SUBROUTINE M01DZF ( COMPAR, M1, M2, IRANK, IFAIL)
INTEGER | M1, M2, IRANK(M2), IFAIL
LOGICAL | COMPAR
EXTERNAL | COMPAR

3 Description

M01DZF is a general purpose routine for ranking arbitrary data. M01DZF does not access the data directly; instead it calls COMPAR to determine the relative ordering of any two data items. The data items are identified simply by an integer in the range M1 to M2.
M01DZF uses a variant of list-merging, as described on pages 165–166 in Knuth (1973). The routine takes advantage of natural ordering in the data, and uses a simple list insertion in a preparatory pass to generate ordered lists of length at least 10.

4 References

Knuth D E (1973) The Art of Computer Programming (Volume 3) (2nd Edition) Addison–Wesley

5 Arguments

1:   COMPAR – LOGICAL FUNCTION, supplied by the user.External Procedure
COMPAR must specify the relative ordering of any two data items; it must return .TRUE. if item I must come strictly after item J in the rank ordering.
The specification of COMPAR is:
FUNCTION COMPAR ( I, J)
LOGICAL COMPAR
INTEGER I, J
1:   I – INTEGERInput
2:   J – INTEGERInput
On entry: I and J identify the data items to be compared.
COMPAR must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which M01DZF is called. Arguments denoted as Input must not be changed by this procedure.
2:   M1 – INTEGERInput
3:   M2 – INTEGERInput
On entry: M1 and M2 must specify the range of data items to be ranked, and the range of ranks to be assigned. Specifically, M01DZF ranks the data items identified by integers in the range M1 to M2, and assigns ranks in the range M1 to M2 which are stored in elements M1 to M2 of IRANK.
Constraint: 0<M1≤M2.
4:   IRANK M2 – INTEGER arrayOutput
On exit: elements M1 to M2 of IRANK contain the ranks of the data items M1 to M2. Note that the ranks are in the range M1 to M2: thus, if item i is first in the rank ordering, IRANK i contains M1.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | M2<1,
or | M1<1,
or | M1>M2.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

M01DZF is not threaded in any implementation.

9 Further Comments

The average time taken by the routine is approximately proportional to n×log n, where n=M2-M1+1; it will usually be dominated by the time taken in COMPAR.

10 Example

This example reads records, each of which contains an integer key and a real number. The program ranks the records first of all in ascending order of the integer key; records with equal keys are ranked in descending order of the real number if the key is negative, in ascending order of the real number if the key is positive, and in their original order if the key is zero. After calling M01DZF, the program calls M01ZAF to convert the ranks to indices, and prints the records in rank order. Note the use of COMMON to communicate the data between the main program and COMPAR.

10.1 Program Text

Program Text (m01dzfe.f90)

10.2 Program Data

Program Data (m01dzfe.d)

10.3 Program Results

Program Results (m01dzfe.r)

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


M01EAF : NAG Library, Mark 26

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

M01EAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

M01EAF rearranges a vector of real numbers into the order specified by a vector of ranks.

2 Specification

SUBROUTINE M01EAF ( RV, M1, M2, IRANK, IFAIL)
INTEGER | M1, M2, IRANK(M2), IFAIL
REAL (KIND=nag_wp) | RV(M2)

3 Description

M01EAF is designed to be used typically in conjunction with the M01D ranking routines. After one of the M01D routines has been called to determine a vector of ranks, M01EAF can be called to rearrange a vector of real numbers into the rank order. If the vector of ranks has been generated in some other way, then M01ZBF should be called to check its validity before M01EAF is called.

4 References

None.

5 Arguments

1:   RV M2 – REAL (KIND=nag_wp) arrayInput/Output
On entry: elements M1 to M2 of RV must contain real values to be rearranged.
On exit: these values are rearranged into rank order. For example, if IRANK i=M1, then the initial value of RV i is moved to RV M1.
2:   M1 – INTEGERInput
3:   M2 – INTEGERInput
On entry: M1 and M2 must specify the range of the ranks supplied in IRANK and the elements of RV to be rearranged.
Constraint: 0<M1≤M2.
4:   IRANK M2 – INTEGER arrayInput/Output
On entry: elements M1 to M2 of IRANK must contain a permutation of the integers M1 to M2, which are interpreted as a vector of ranks.
On exit: used as internal workspace prior to being restored and hence is unchanged.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | M2<1,
or | M1<1,
or | M1>M2.
IFAIL=2
Elements M1 to M2 of IRANK contain a value outside the range M1 to M2.
IFAIL=3
Elements M1 to M2 of IRANK contain a repeated value.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.
If IFAIL=2 or 3, elements M1 to M2 of IRANK do not contain a permutation of the integers M1 to M2. On exit, the contents of RV may be corrupted. To check the validity of IRANK without the risk of corrupting RV, use M01ZBF.

7 Accuracy

Not applicable.

8 Parallelism and Performance

M01EAF is not threaded in any implementation.

9 Further Comments

The average time taken by the routine is approximately proportional to n, where n=M2-M1+1.

10 Example

This example reads a matrix of real numbers and rearranges its rows so that the elements of the kth column are in ascending order. To do this, the program first calls M01DAF to rank the elements of the kth column, and then calls M01EAF to rearrange each column into the order specified by the ranks. The value of k is read from the datafile.

10.1 Program Text

Program Text (m01eafe.f90)

10.2 Program Data

Program Data (m01eafe.d)

10.3 Program Results

Program Results (m01eafe.r)

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


M01EBF : NAG Library, Mark 26

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

M01EBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

M01EBF rearranges a vector of integer numbers into the order specified by a vector of ranks.

2 Specification

SUBROUTINE M01EBF ( IV, M1, M2, IRANK, IFAIL)
INTEGER IV(M2), M1, M2, IRANK(M2), IFAIL

3 Description

M01EBF is designed to be used typically in conjunction with the M01D ranking routines. After one of the M01D routines has been called to determine a vector of ranks, M01EBF can be called to rearrange a vector of integer numbers into the rank order. If the vector of ranks has been generated in some other way, then M01ZBF should be called to check its validity before M01EBF is called.

4 References

None.

5 Arguments

1:   IV M2 – INTEGER arrayInput/Output
On entry: elements M1 to M2 of IV must contain integer values to be rearranged.
On exit: these values are rearranged into rank order. For example, if IRANK i=M1, then the initial value of IV i is moved to IV M1.
2:   M1 – INTEGERInput
3:   M2 – INTEGERInput
On entry: M1 and M2 specify the range of the ranks supplied in IRANK and the elements of IV to be rearranged.
Constraint: 0<M1≤M2.
4:   IRANK M2 – INTEGER arrayInput/Output
On entry: elements M1 to M2 of IRANK must contain a permutation of the integers M1 to M2, which are interpreted as a vector of ranks.
On exit: used as internal workspace prior to being restored and hence is unchanged.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | M2<1,
or | M1<1,
or | M1>M2.
IFAIL=2
Elements M1 to M2 of IRANK contain a value outside the range M1 to M2.
IFAIL=3
Elements M1 to M2 of IRANK contain a repeated value.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.
If IFAIL=2 or 3, elements M1 to M2 of IRANK do not contain a permutation of the integers M1 to M2. On exit, the contents of IV may be corrupted. To check the validity of IRANK without the risk of corrupting IV, use M01ZBF.

7 Accuracy

Not applicable.

8 Parallelism and Performance

M01EBF is not threaded in any implementation.

9 Further Comments

The average time taken by the routine is approximately proportional to n, where n=M2-M1+1.

10 Example

This example reads a matrix of integers and rearranges its rows so that the elements of the kth column are in ascending order. To do this, the program first calls M01DBF to rank the elements of the kth column, and then calls M01EBF to rearrange each column into the order specified by the ranks. The value of k is read from the datafile.

10.1 Program Text

Program Text (m01ebfe.f90)

10.2 Program Data

Program Data (m01ebfe.d)

10.3 Program Results

Program Results (m01ebfe.r)

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


M01ECF : NAG Library, Mark 26

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

M01ECF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

M01ECF rearranges a vector of character data into the order specified by a vector of ranks.

2 Specification

SUBROUTINE M01ECF ( CH, M1, M2, IRANK, IFAIL)
INTEGER | M1, M2, IRANK(M2), IFAIL
CHARACTER(*) | CH(M2)

3 Description

M01ECF is designed to be used typically in conjunction with the M01D ranking routines. After one of the M01D routines has been called to determine a vector of ranks, M01ECF can be called to rearrange a vector of character data into the rank order. If the vector of ranks has been generated in some other way, then M01ZBF should be called to check its validity before M01ECF is called.

4 References

None.

5 Arguments

1:   CH M2 – CHARACTER(*) arrayInput/Output
On entry: elements M1 to M2 of CH must contain character data to be rearranged.
Constraint: the length of each element of CH must not exceed 255.
On exit: these values are rearranged into rank order. For example, if IRANK i=M1, then the initial value of CH i is moved to CH M1.
2:   M1 – INTEGERInput
3:   M2 – INTEGERInput
On entry: the range of the ranks supplied in IRANK and the elements of CH to be rearranged.
Constraint: 0<M1≤M2.
4:   IRANK M2 – INTEGER arrayInput/Output
On entry: elements M1 to M2 of IRANK must contain a permutation of the integers M1 to M2, which are interpreted as a vector of ranks.
On exit: used as internal workspace prior to being restored and hence is unchanged.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | M2<1,
or | M1<1,
or | M1>M2.
IFAIL=2
On entry, the length of each element of CH exceeds 255.
IFAIL=3
Elements M1 to M2 of IRANK contain a value outside the range M1 to M2.
IFAIL=4
Elements M1 to M2 of IRANK contain a repeated value.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.
If IFAIL=3 or 4, elements M1 to M2 of IRANK do not contain a permutation of the integers M1 to M2. On exit, the contents of CH may be corrupted. To check the validity of IRANK without the risk of corrupting CH, use M01ZBF.

7 Accuracy

Not applicable.

8 Parallelism and Performance

M01ECF is not threaded in any implementation.

9 Further Comments

The average time taken by the routine is approximately proportional to n, where n=M2-M1+1.

10 Example

This example reads a file of 12-character records, each of which contains in characters 1 to 6 a name of a NAG routine, and in characters 7 to 12 an integer frequency. The program first calls M01DBF to rank the integers in descending order, and then calls M01ECF to rearrange the names into the order specified by the ranks.

10.1 Program Text

Program Text (m01ecfe.f90)

10.2 Program Data

Program Data (m01ecfe.d)

10.3 Program Results

Program Results (m01ecfe.r)

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


M01EDF : NAG Library, Mark 26

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

M01EDF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

M01EDF rearranges a vector of complex numbers into the order specified by a vector of ranks.

2 Specification

SUBROUTINE M01EDF ( CV, M1, M2, IRANK, IFAIL)
INTEGER | M1, M2, IRANK(M2), IFAIL
COMPLEX (KIND=nag_wp) | CV(M2)

3 Description

M01EDF is designed to be used typically in conjunction with the M01D ranking routines. After one of the M01D routines has been called to determine a vector of ranks, M01EDF can be called to rearrange a vector of complex numbers into the rank order. If the vector of ranks has been generated in some other way, then M01ZBF should be called to check its validity before M01EDF is called.

4 References

None.

5 Arguments

1:   CV M2 – COMPLEX (KIND=nag_wp) arrayInput/Output
On entry: elements M1 to M2 of CV must contain complex values to be rearranged.
On exit: these values are rearranged into rank order. For example, if IRANK i=M1, then the initial value of CV i is moved to CV M1.
2:   M1 – INTEGERInput
3:   M2 – INTEGERInput
On entry: M1 and M2 must specify the range of the ranks supplied in IRANK and the elements of CV to be rearranged.
Constraint: 0<M1≤M2.
4:   IRANK M2 – INTEGER arrayInput/Output
On entry: elements M1 to M2 of IRANK must contain a permutation of the integers M1 to M2, which are interpreted as a vector of ranks.
On exit: used as internal workspace prior to being restored and hence is unchanged.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | M2<1,
or | M1<1,
or | M1>M2.
IFAIL=2
Elements M1 to M2 of IRANK contain a value outside the range M1 to M2.
IFAIL=3
Elements M1 to M2 of IRANK contain a repeated value.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.
If IFAIL=2 or 3, elements M1 to M2 of IRANK do not contain a permutation of the integers M1 to M2. On exit, the contents of CV may be corrupted. To check the validity of IRANK without the risk of corrupting CV, use M01ZBF.

7 Accuracy

Not applicable.

8 Parallelism and Performance

M01EDF is not threaded in any implementation.

9 Further Comments

The average time taken by the routine is approximately proportional to n, where n=M2-M1+1.

10 Example

This example reads a matrix of complex numbers and rearranges its rows so that the elements in the kth column are in ascending order of modulus. To do this, the program first calls M01DAF to rank the moduli of the elements in the kth column, and then calls M01EDF to rearrange each column into the order specified by the ranks. The value of k is read from the datafile.

10.1 Program Text

Program Text (m01edfe.f90)

10.2 Program Data

Program Data (m01edfe.d)

10.3 Program Results

Program Results (m01edfe.r)

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


M01 Chapter Introduction : NAG Library, Mark 26

M01 Chapter Contents

NAG Library Chapter Introduction

M01 – Sorting and Searching

▸▿ Contents

1 Scope of the Chapter
▸▿ 2 Background to the Problems
2.1 Sorting
2.2 Searching
3 Recommendations on Choice and Use of Available Routines
4 Functionality Index
5 Auxiliary Routines Associated with Library Routine Arguments
6 Routines Withdrawn or Scheduled for Withdrawal
7 References

1 Scope of the Chapter

This chapter is concerned with sorting and searching numeric or character data. It handles only the simplest types of data structure and it is concerned only with internal sorting and searching – that is, sorting and searching a set of data which can all be stored within the program.
If you have large files of data or complicated data structures to be sorted or searched you should use a comprehensive sorting or searching program or package.

2 Background to the Problems

2.1 Sorting

The usefulness of sorting is obvious (perhaps a little too obvious, since sorting can be expensive and is sometimes done when not strictly necessary). Sorting may traditionally be associated with data processing and non-numerical programming, but it has many uses within the realm of numerical analysis. For example, within the NAG Library, sorting is used to arrange eigenvalues in ascending order of absolute value, in the manipulation of sparse matrices, and in the ranking of observations for nonparametric statistics.
The general problem may be defined as follows. We are given N items of data
R 1,R 2,…,RN.
Each item Ri contains a key Ki which can be ordered relative to any other key according to some specified criterion (for example, ascending numeric value). The problem is to determine a permutation
p 1,p 2,…,p N
which puts the keys in order:
K p 1≤K p 2≤…≤K p N.
Sometimes we may wish actually to rearrange the items so that their keys are in order; for other purposes we may simply require a table of indices so that the items can be referred to in sorted order; or yet again we may require a table of ranks, that is, the positions of each item in the sorted order.
For example, given the single-character items, to be sorted into alphabetic order
  • E B A D C
the indices of the items in sorted order are
  • 3 2 5 4 1
and the ranks of the items are
  • 5 2 1 4 3.
Indices may be converted to ranks, and vice versa, by simply computing the inverse permutation.
The items may consist solely of the key (each item may simply be a number). On the other hand, the items may contain additional information (for example, each item may be an eigenvalue of a matrix and its associated eigenvector, the eigenvalue being the key). In the latter case there may be many distinct items with equal keys, and it may be important to preserve the original order among them (if this is achieved, the sorting is called ‘stable’).
There are a number of ingenious algorithms for sorting. For a fascinating discussion of them, and of the whole subject, see Knuth (1973).

2.2 Searching

Searching is a process of retrieving data stored in a computer's memory.
The general problem may be defined as follows:
  • We are given n items of data that have been sorted and a sought-after item x. Each item contains a key. The problem is to find which item has x as its key.
  • We may be interested in different information gained from the search. We may wish to know if item x was or was not found or the position of the item that was found.
There are a number of different search algorithms. For more on the subject, see Knuth (1973) and Wirth (2004).

3 Recommendations on Choice and Use of Available Routines

The following categories of routines are provided:
  • – routines which rearrange the data into sorted order (M01C);
  • – routines which determine the ranks of the data, leaving the data unchanged (M01D);
  • – routines which rearrange the data according to pre-determined ranks (M01E);
  • – routines which search the data (M01N);
  • – service routines (M01Z).
In the first two and the fourth categories routines are provided for real and integer numeric data, and for character data. In the third category there are routines for rearranging real, complex , integer and character data. Utilities for the manipulation of sparse matrices can be found in Chapter F11.
If the task is simply to rearrange a one-dimensional array of data into sorted order, then an M01C routine should be used, since this requires no extra workspace and is faster than any other method. There are no M01C routines for more complicated data structures, because the cost of rearranging the data is likely to outstrip the cost of comparisons. Instead, a combination of M01D and M01E routines, or some other approach, must be used as described below.
For many applications it is in fact preferable to separate the task of determining the sorted order (ranking) from the task of rearranging data into a pre-determined order; the latter task may not need to be performed at all. Frequently it may be sufficient to refer to the data in sorted order via an index vector, without rearranging it. Frequently also one set of data (e.g., a column of a matrix) is used for determining a set of ranks, which are then applied to other data (e.g., the remaining columns of the matrix).
To determine the ranks of a set of data, use an M01D routine. Routines are provided for ranking one-dimensional arrays, and for ranking rows or columns of two-dimensional arrays. For ranking an arbitrary data structure, use M01DZF, which is, however, much less efficient than the other M01D routines.
To create an index vector so that data can be referred to in sorted order, first call an M01D routine to determine the ranks, and then call M01ZAF to convert the vector of ranks into an index vector.
To rearrange data according to pre-determined ranks: use an M01E routine if the data is stored in a one-dimensional array; or if the data is stored in a more complicated structure
  • either use an index vector to generate a new copy of the data in the desired order
  • or rearrange the data without using extra storage by first calling M01ZCF and then using the simple code-framework given in the document for M01ZCF (assuming that the elements of data all occupy equal storage).
To search for an item in a one-dimensional sorted array of data, use an M01N routine. These routines return the index of the first item with the key equal to the sought-after item or if it is not found, the index of the last item containing the biggest value less than the sought-after item.
Examples of these operations can be found in the routine documents of the relevant routines.

4 Functionality Index

Ranking,
arbitrary data M01DZF
columns of a matrix,
integer numbers M01DKF
real numbers M01DJF
rows of a matrix,
integer numbers M01DFF
real numbers M01DEF
vector,
character data M01DCF
integer numbers M01DBF
real numbers M01DAF
Rearranging (according to pre-determined ranks):
vector,
character data M01ECF
complex numbers M01EDF
integer numbers M01EBF
real numbers M01EAF
Searching (i.e., exact match or the nearest lower value):
binary search,
vector,
integer numbers M01NBF
null terminated strings M01NCF
real numbers M01NAF
Service routines,
check validity of a permutation M01ZBF
decompose a permutation into cycles M01ZCF
invert a permutation (ranks to indices or vice versa) M01ZAF
Sorting (i.e., rearranging into sorted order):
quick sort,
vector,
character data M01CCF
integer numbers M01CBF
real numbers M01CAF

5 Auxiliary Routines Associated with Library Routine Arguments

None.

6 Routines Withdrawn or Scheduled for Withdrawal

None.

7 References

Knuth D E (1973) The Art of Computer Programming (Volume 3) (2nd Edition) Addison–Wesley
Wirth N (2004) Algorithms and Data Structures 35–36 Prentice Hall
M01 Chapter Contents
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


M01NAF : NAG Library, Mark 26

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

M01NAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

M01NAF searches an ordered vector of real numbers and returns the index of the first value equal to the sought-after item.

2 Specification

FUNCTION M01NAF ( VALID, RV, M1, M2, ITEM, IFAIL)
INTEGER M01NAF
INTEGER | M1, M2, IFAIL
REAL (KIND=nag_wp) | RV(M2), ITEM
LOGICAL | VALID

3 Description

M01NAF is based on Professor Niklaus Wirth's implementation of the Binary Search algorithm (see Wirth (2004)), but with two modifications. First, if the sought-after item is less than the value of the first element of the array to be searched, 0 is returned. Second, if a value equal to the sought-after item is not found, the index of the immediate lower value is returned.

4 References

Wirth N (2004) Algorithms and Data Structures 35–36 Prentice Hall

5 Arguments

1:   VALID – LOGICALInput
On entry: if VALID is set to .TRUE. argument checking will be performed. If VALID is set to .FALSE. M01NAF will be called without argument checking (which includes checking that array RV is sorted in ascending order) and the routine will return with IFAIL=0. See Section 9 for further details.
2:   RV M2 – REAL (KIND=nag_wp) arrayInput
On entry: elements M1 to M2 contain real values to be searched.
Constraint: elements M1 to M2 of RV must be sorted in ascending order.
3:   M1 – INTEGERInput
On entry: the index of the first element of RV to be searched.
Constraint: M1≥1.
4:   M2 – INTEGERInput
On entry: the index of the last element of RV to be searched.
Constraint: M2≥M1.
5:   ITEM – REAL (KIND=nag_wp)Input
On entry: the sought-after item.
6:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
(Note: these errors will only be returned if VALID=.TRUE..)
IFAIL=2
On entry, RV must be sorted in ascending order: RV​ element ​value>​ element ​value.
IFAIL=3
On entry, M1=value.
Constraint: M1≥1.
IFAIL=4
On entry, M1=value, M2=value.
Constraint: M1≤M2.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

M01NAF is not threaded in any implementation.

9 Further Comments

The argument VALID should be used with caution. Set it to .FALSE. only if you are confident that the other arguments are correct, in particular that array RV is in fact arranged in ascending order. If you wish to search the same array RV many times, you are recommended to set VALID to .TRUE. on first call of M01NAF and to .FALSE. on subsequent calls, in order to minimize the amount of time spent checking RV, which may be significant if RV is large.
The time taken by M01NAF is O log n, where n=M2-M1+1, when VALID=.FALSE..

10 Example

This example reads a list of double precision numbers and sought-after items and performs the search for these items.

10.1 Program Text

Program Text (m01nafe.f90)

10.2 Program Data

Program Data (m01nafe.d)

10.3 Program Results

Program Results (m01nafe.r)

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


M01NBF : NAG Library, Mark 26

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

M01NBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

M01NBF searches an ordered vector of integer numbers and returns the index of the first value equal to the sought-after item.

2 Specification

FUNCTION M01NBF ( VALID, IV, M1, M2, ITEM, IFAIL)
INTEGER M01NBF
INTEGER | IV(M2), M1, M2, ITEM, IFAIL
LOGICAL | VALID

3 Description

M01NBF is based on Professor Niklaus Wirth's implementation of the Binary Search algorithm (see Wirth (2004)), but with two modifications. First, if the sought-after item is less than the value of the first element of the array to be searched, 0 is returned. Second, if a value equal to the sought-after item is not found, the index of the immediate lower value is returned.

4 References

Wirth N (2004) Algorithms and Data Structures 35–36 Prentice Hall

5 Arguments

1:   VALID – LOGICALInput
On entry: if VALID is set to .TRUE. argument checking will be performed. If VALID is set to .FALSE. M01NBF will be called without argument checking (which includes checking that array IV is sorted in ascending order) and the routine will return with IFAIL=0. See Section 9 for further details.
2:   IV M2 – INTEGER arrayInput
On entry: elements M1 to M2 contain integer values to be searched.
Constraint: elements M1 to M2 of IV must be sorted in ascending order.
3:   M1 – INTEGERInput
On entry: the index of the first element of IV to be searched.
Constraint: M1≥1.
4:   M2 – INTEGERInput
On entry: the index of the last element of IV to be searched.
Constraint: M2≥M1.
5:   ITEM – INTEGERInput
On entry: the sought-after item.
6:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
(Note: these errors will only be returned if VALID=.TRUE..)
IFAIL=2
On entry, IV must be sorted in ascending order: IV​ element ​value>​ element ​value.
IFAIL=3
On entry, M1=value.
Constraint: M1≥1.
IFAIL=4
On entry, M1=value, M2=value.
Constraint: M1≤M2.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

M01NBF is not threaded in any implementation.

9 Further Comments

The argument VALID should be used with caution. Set it to .FALSE. only if you are confident that the other arguments are correct, in particular that array IV is in fact arranged in ascending order. If you wish to search the same array IV many times, you are recommended to set VALID to .TRUE. on first call of M01NBF and to .FALSE. on subsequent calls, in order to minimize the amount of time spent checking IV, which may be significant if IV is large.
The time taken by M01NBF is O log n, where n=M2-M1+1, when VALID=.FALSE..

10 Example

This example reads a list of integer numbers and sought-after items and performs the search for these items.

10.1 Program Text

Program Text (m01nbfe.f90)

10.2 Program Data

Program Data (m01nbfe.d)

10.3 Program Results

Program Results (m01nbfe.r)

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


M01NCF : NAG Library, Mark 26

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

M01NCF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

M01NCF examines an ordered vector of null terminated strings and returns the index of the first value equal to the sought-after item. Character items are compared according to the ASCII collating sequence.

2 Specification

FUNCTION M01NCF ( VALID, CH, M1, M2, ITEM, IFAIL)
INTEGER M01NCF
INTEGER | M1, M2, IFAIL
LOGICAL | VALID
CHARACTER(*) | CH(M2), ITEM

3 Description

M01NCF is based on Professor Niklaus Wirth's implementation of the Binary Search algorithm (see Wirth (2004)), but with two modifications. First, if the sought-after item is less than the value of the first element of the array to be searched, 0 is returned. Second, if a value equal to the sought-after item is not found, the index of the immediate lower value is returned.

4 References

Wirth N (2004) Algorithms and Data Structures 35–36 Prentice Hall

5 Arguments

1:   VALID – LOGICALInput
On entry: if VALID is set to .TRUE. argument checking will be performed. If VALID is set to .FALSE. M01NCF will be called without argument checking, which includes checking that array CH is sorted in ascending order and the routine will return with IFAIL=0. See Section 9 for further details.
2:   CH M2 – CHARACTER(*) arrayInput
On entry: elements M1 to M2 contain character data to be searched.
Constraint: elements M1 to M2 of CH must be sorted in ascending order. The length of each element of CH must not exceed 255. Trailing space characters are ignored.
3:   M1 – INTEGERInput
On entry: the index of the first element of CH to be searched.
Constraint: M1≥1.
4:   M2 – INTEGERInput
On entry: the index of the last element of CH to be searched.
Constraint: M2≥M1.
5:   ITEM – CHARACTER(*)Input
On entry: the sought-after item. Trailing space characters are ignored.
6:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
(Note: these errors will only be returned if VALID=.TRUE..)
IFAIL=2
On entry, CH must be sorted in ascending order: CH​ element ​value>​ element ​value.
IFAIL=3
On entry, M1=value.
Constraint: M1≥1.
IFAIL=4
On entry, M1=value, M2=value.
Constraint: M2≥M1.
IFAIL=5
On entry, the length of each element of CH must be at most 255: maximum string length =value.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

M01NCF is not threaded in any implementation.

9 Further Comments

The argument VALID should be used with caution. Set it to .FALSE. only if you are confident that the other arguments are correct, in particular that array CH is in fact arranged in ascending order. If you wish to search the same array CH many times, you are recommended to set VALID to .TRUE. on first call of M01NCF and to .FALSE. on subsequent calls, in order to minimize the amount of time spent checking CH, which may be significant if CH is large.
The time taken by M01NCF is O log n, where n=M2-M1+1, when VALID=.FALSE..

10 Example

This example reads a list of character data and sought-after items and performs the search for these items.

10.1 Program Text

Program Text (m01ncfe.f90)

10.2 Program Data

Program Data (m01ncfe.d)

10.3 Program Results

Program Results (m01ncfe.r)

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


M01ZAF : NAG Library, Mark 26

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

M01ZAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

M01ZAF inverts a permutation, and hence converts a rank vector to an index vector, or vice versa.

2 Specification

SUBROUTINE M01ZAF ( IPERM, M1, M2, IFAIL)
INTEGER IPERM(M2), M1, M2, IFAIL

3 Description

There are two common ways of describing a permutation using an integer vector IPERM. The first uses ranks: IPERM i holds the position to which the ith data element should be moved in order to sort the data; in other words its rank in the sorted order. The second uses indices: IPERM i holds the current position of the data element which would occur in ith position in sorted order. For example, given the values
3.5 5.9 2.9 0.5
to be sorted in ascending order, the ranks would be
3.0   4.0   2.0   1.0
and the indices would be
4.0   3.0   1.0   2.0
The M01D routines generate ranks, and the M01E routines require ranks to be supplied to specify the reordering. However if it is desired simply to refer to the data in sorted order without actually reordering them, indices are more convenient than ranks (see the example in Section 10).
M01ZAF can be used to convert ranks to indices, or indices to ranks, as the two permutations are inverses of each another.

4 References

None.

5 Arguments

1:   IPERM M2 – INTEGER arrayInput/Output
On entry: elements M1 to M2 of IPERM must contain a permutation of the integers M1 to M2.
On exit: these elements contain the inverse permutation of the integers M1 to M2.
2:   M1 – INTEGERInput
3:   M2 – INTEGERInput
On entry: M1 and M2 must specify the range of elements used in the array IPERM and the range of values in the permutation, as specified under IPERM.
Constraint: 0<M1≤M2.
4:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | M2<1,
or | M1<1,
or | M1>M2.
IFAIL=2
Elements M1 to M2 of IPERM contain a value outside the range M1 to M2.
IFAIL=3
Elements M1 to M2 of IPERM contain a repeated value.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.
If IFAIL=2 or 3, elements M1 to M2 of IPERM do not contain a permutation of the integers M1 to M2; on exit these elements are usually corrupted. To check the validity of a permutation without the risk of corrupting it, use M01ZBF.

7 Accuracy

Not applicable.

8 Parallelism and Performance

M01ZAF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads a matrix of real numbers and prints its rows in ascending order as ranked by M01DEF. The program first calls M01DEF to rank the rows, and then calls M01ZAF to convert the rank vector to an index vector, which is used to refer to the rows in sorted order.

10.1 Program Text

Program Text (m01zafe.f90)

10.2 Program Data

Program Data (m01zafe.d)

10.3 Program Results

Program Results (m01zafe.r)

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


M01ZBF : NAG Library, Mark 26

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

M01ZBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

M01ZBF checks the validity of a permutation.

2 Specification

SUBROUTINE M01ZBF ( IPERM, M1, M2, IFAIL)
INTEGER IPERM(M2), M1, M2, IFAIL

3 Description

M01ZBF can be used to check the validity of user-supplied ranks or indices, without the ranks or indices being corrupted.

4 References

None.

5 Arguments

1:   IPERM M2 – INTEGER arrayInput/Output
On entry: elements M1 to M2 of IPERM must be set to values which are supposed to be a permutation of the integers M1 to M2. If they are a valid permutation, the routine exits with IFAIL=0.
On exit: used as internal workpsace prior to being restored and hence is unchanged.
2:   M1 – INTEGERInput
3:   M2 – INTEGERInput
On entry: the range of elements used in the array IPERM and the range of values in the permutation, as specified under IPERM.
Constraint: 0<M1≤M2.
4:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | M2<1,
or | M1<1,
or | M1>M2.
IFAIL=2
Elements M1 to M2 of IPERM contain a value outside the range M1 to M2.
IFAIL=3
Elements M1 to M2 of IPERM contain a repeated value.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.
If IFAIL=2 or 3, elements M1 to M2 of IPERM do not contain a permutation of the integers M1 to M2.

7 Accuracy

Not applicable.

8 Parallelism and Performance

M01ZBF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads in a vector of real numbers, and a vector of ranks; it calls M01ZBF to check the validity of the ranks before calling M01EAF to rearrange the real numbers into the specified order.

10.1 Program Text

Program Text (m01zbfe.f90)

10.2 Program Data

Program Data (m01zbfe.d)

10.3 Program Results

Program Results (m01zbfe.r)

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


M01ZCF : NAG Library, Mark 26

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

M01ZCF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

M01ZCF decomposes a permutation into cycles, as an aid to reordering ranked data.

2 Specification

SUBROUTINE M01ZCF ( IPERM, M1, M2, ICYCL, IFAIL)
INTEGER IPERM(M2), M1, M2, ICYCL(M2), IFAIL

3 Description

M01ZCF is provided as an aid to reordering arbitrary data structures without using additional storage. However, you should consider carefully whether it is necessary to rearrange yourr data, or whether it would be simpler and more efficient to refer to the data in sorted order using an index vector, or to create a copy of the data in sorted order.
To rearrange data into a different order without using additional storage, the simplest method is to decompose the permutation which specifies the new order into cycles and then to do a cyclic permutation of the data items in each cycle. (This is the method used by the M01E reordering routines.) Given a vector IRANK which specifies the ranks of the data (as generated by the M01D routines), M01ZCF generates a new vector ICYCL, in which the permutation is represented in its component cycles, with the first element of each cycle negated. For example, the permutation
5 7 4 2 1 6 3
is composed of the cycles
1 5 2 7 3 4 6
and the vector ICYCL generated by M01ZCF contains
-1 5 -2 7 3 4 -6
In order to rearrange the data according to the specified ranks:
  • item 6 must be left in place;
  • items 1 and 5 must be interchanged;
  • items 4, 2, 7 and 3 must be moved right one place round the cycle.
The complete rearrangement can be achieved by the following code:
DO 10 K = M1, M2
I = ICYCL(K)
IF (I.LT.0) THEN
J = -I
ELSE
[swap items I and J]
ENDIF
10 CONTINUE

4 References

None.

5 Arguments

1:   IPERM M2 – INTEGER arrayInput/Output
On entry: elements M1 to M2 of IPERM must contain a permutation of the integers M1 to M2.
On exit: is used as internal workpsace prior to being restored and hence is unchanged.
2:   M1 – INTEGERInput
3:   M2 – INTEGERInput
On entry: M1 and M2 must specify the range of elements used in the array IPERM and the range of values in the permutation, as specified under IPERM.
Constraint: 0<M1≤M2.
4:   ICYCL M2 – INTEGER arrayOutput
On exit: elements M1 to M2 of ICYCL contain a representation of the permutation as a list of cycles, with the first integer in each cycle negated. (See Section 3.)
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | M2<1,
or | M1<1,
or | M1>M2.
IFAIL=2
Elements M1 to M2 of IPERM contain a value outside the range M1 to M2.
IFAIL=3
Elements M1 to M2 of IPERM contain a repeated value.
If IFAIL=2 or 3, elements M1 to M2 of IPERM do not contain a permutation of the integers M1 to M2.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

M01ZCF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads a matrix of real numbers and rearranges its columns so that the elements of the lth row are in ascending order. To do this, the program first calls M01DJF to rank the elements of the lth row, and then calls M01ZCF to decompose the rank vector into cycles. It then rearranges the columns using the framework of code suggested in Section 3. The value of l is read from the data file.

10.1 Program Text

Program Text (m01zcfe.f90)

10.2 Program Data

Program Data (m01zcfe.d)

10.3 Program Results

Program Results (m01zcfe.r)

M01 Chapter Contents
M01 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


This is release branch v2.1 of MathJax.


S01BAF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S01BAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S01BAF returns a value of the shifted logarithmic function, ln 1+x, via the function name.

2 Specification

FUNCTION S01BAF ( X, IFAIL)
REAL (KIND=nag_wp) S01BAF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S01BAF computes values of ln 1+x, retaining full relative precision even when x is small. The routine is based on the Chebyshev expansion
ln⁡1+p 2+2 p x- 1+p 2-2 p x- =4∑k=0∞p 2 k+1 2 k+1 T 2 k+1 x-.
Setting x-= x 1+p 2 2 p x+2 , and choosing p= q-1 q+1 , q=24 the expansion is valid in the domain x∈ 1 2-1,2-1 .
Outside this domain, ln 1+x is computed by the standard logarithmic function.

4 References

Lyusternik L A, Chervonenkis O A and Yanpolskii A R (1965) Handbook for Computing Elementary Functions p. 57 Pergamon Press

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
Constraint: X>-1.0.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, X≤-1.0.
The result is returned as zero.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The returned result should be accurate almost to machine precision, with a limit of about 20 significant figures due to the precision of internal constants. Note however that if x lies very close to -1.0 and is not exact (for example if x is the result of some previous computation and has been rounded), then precision will be lost in the computation of 1+x, and hence ln 1+x, in S01BAF.

8 Parallelism and Performance

S01BAF is not threaded in any implementation.

9 Further Comments

Empirical tests show that the time taken for a call of S01BAF usually lies between about 1.25 and 2.5 times the time for a call to the standard logarithm function.

10 Example

The example program reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s01bafe.f90)

10.2 Program Data

Program Data (s01bafe.d)

10.3 Program Results

Program Results (s01bafe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S01EAF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S01EAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S01EAF evaluates the exponential function ez, for complex z.

2 Specification

FUNCTION S01EAF ( Z, IFAIL)
COMPLEX (KIND=nag_wp) S01EAF
INTEGER | IFAIL
COMPLEX (KIND=nag_wp) | Z

3 Description

S01EAF evaluates the exponential function ez, taking care to avoid machine overflow, and giving a warning if the result cannot be computed to more than half precision. The function is evaluated as ez=ex cos⁡y+i sin⁡y, where x and y are the real and imaginary parts respectively of z.
Since cos⁡y and sin⁡y are less than or equal to 1 in magnitude, it is possible that ex may overflow although ex cos⁡y or ex sin⁡y does not. In this case the alternative formula sign cos⁡y e x+ln cos⁡y is used for the real part of the result, and sign sin⁡y e x+ln sin⁡y for the imaginary part. If either part of the result still overflows, a warning is returned through argument IFAIL.
If Im z is too large, precision may be lost in the evaluation of sin⁡y and cos⁡y. Again, a warning is returned through IFAIL.

4 References

None.

5 Arguments

1:   Z – COMPLEX (KIND=nag_wp)Input
On entry: the argument z of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
The real part of the result overflows, and is set to the largest safe number with the correct sign. The imaginary part of the result is meaningful.
IFAIL=2
The imaginary part of the result overflows, and is set to the largest safe number with the correct sign. The real part of the result is meaningful.
IFAIL=3
Both real and imaginary parts of the result overflow, and are set to the largest safe number with the correct signs.
IFAIL=4
The computed result is accurate to less than half precision, due to the size of Im z.
IFAIL=5
The computed result has no precision, due to the size of Im z, and is set to zero.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Accuracy is limited in general only by the accuracy of the standard functions in the computation of sin⁡y, cos⁡y and ex, where x=Re z, y=Im z. As y gets larger, precision will probably be lost due to argument reduction in the evaluation of the sine and cosine functions, until the warning error IFAIL=4 occurs when y gets larger than 1/ε, where ε is the machine precision. Note that on some machines, the intrinsic functions SIN and COS will not operate on arguments larger than about 1/ε, and so IFAIL can never return as 4.
In the comparatively rare event that the result is computed by the formulae sign cos⁡y e x+ln cos⁡y and sign sin⁡y e x+ln sin⁡y, a further small loss of accuracy may be expected due to rounding errors in the logarithmic function.

8 Parallelism and Performance

S01EAF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument z from a file, evaluates the function at each value of z and prints the results.

10.1 Program Text

Program Text (s01eafe.f90)

10.2 Program Data

Program Data (s01eafe.d)

10.3 Program Results

Program Results (s01eafe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S07AAF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S07AAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S07AAF returns the value of the circular tangent, tan⁡x, via the function name.

2 Specification

FUNCTION S07AAF ( X, IFAIL)
REAL (KIND=nag_wp) S07AAF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S07AAF calculates an approximate value for the circular tangent of its argument, tan⁡x. It is based on the Chebyshev expansion
tan⁡θ=θy t=θ∑′r=0 crTr t
where - π 4<θ< π 4 and -1 <t<+1 ,   t=2 4 θ π 2-1 .
The reduction to the standard range is accomplished by taking
x=Nπ/2+θ
where N is an integer and -π 4<θ<π 4 ,
i.e., θ=x- 2 x π π 2 where N = 2 x π = ​ the nearest integer to ​ 2 x π .
From the properties of tan⁡x it follows that
tan⁡x= tan⁡θ, Neven -1/tan⁡θ, Nodd

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
The routine has been called with an argument that is larger in magnitude than F; the default result returned is zero. The value of F is given in the Users' Note for your implementation.
IFAIL=2
The routine has been called with an argument that is too close (as determined using the relative tolerance F) to an odd multiple of π/2, at which the function is infinite; the routine returns a value with the correct sign but a more or less arbitrary but large magnitude (see Section 7). The value of F is given in the Users' Note for your implementation.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

If δ and ε are the relative errors in the argument and result respectively, then in principle
ε≥2 x sin⁡2 x δ.
That is a relative error in the argument, x, is amplified by at least a factor 2 x/sin⁡2 x in the result.
Similarly if E is the absolute error in the result this is given by
E≥x cos 2 x δ.
The equalities should hold if δ is greater than the machine precision (δ is a result of data errors etc.) but if δ is simply the round-off error in the machine it is possible that internal calculation rounding will lose an extra figure.
The graphs below show the behaviour of these amplification factors.
GnuplotProduced by GNUPLOT 4.6 patchlevel 3 100 101 102 0 π/2 π 3π/2 2π 5π/2 3π 7π/2 |ε/δ| x gnuplot_plot_1
Figure 1
GnuplotProduced by GNUPLOT 4.6 patchlevel 3 100 101 102 0 π/2 π 3π/2 2π 5π/2 3π 7π/2 |ε/δ| x gnuplot_plot_1
Figure 2
In the principal range it is possible to preserve relative accuracy even near the zero of tan⁡x at x=0 but at the other zeros only absolute accuracy is possible. Near the infinities of tan⁡x both the relative and absolute errors become infinite and the routine must fail (error 2).
If N is odd and θ≤x F 2 the routine could not return better than two figures and in all probability would produce a result that was in error in its most significant figure. Therefore the routine fails and it returns the value
-sign⁡θ 1 x F 2 ≃-sign⁡θtan π 2-x F 2
which is the value of the tangent at the nearest argument for which a valid call could be made.
Accuracy is also unavoidably lost if the routine is called with a large argument. If x>F 1 the routine fails (error 1) and returns zero. (See the Users' Note for your implementation for specific values of F 1 and F 2.)

8 Parallelism and Performance

S07AAF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s07aafe.f90)

10.2 Program Data

Program Data (s07aafe.d)

10.3 Program Results

Program Results (s07aafe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S09AAF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S09AAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S09AAF returns the value of the inverse circular sine, arcsin⁡x, via the function name. The value is in the principal range -π/2,π/2.

2 Specification

FUNCTION S09AAF ( X, IFAIL)
REAL (KIND=nag_wp) S09AAF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S09AAF calculates an approximate value for the inverse circular sine, arcsin⁡x. It is based on the Chebyshev expansion
arcsin⁡x=x×y x=x∑′r=0 arTr t
where - 1 2≤x≤ 1 2 and t=4 x 2-1.
For x 2≤ 12,  arcsin⁡x=x×y x.
For 12<x 2≤1,  arcsin⁡x=sign⁡x π 2-arcsin⁡1-x 2 .
For x 2>1,  arcsin⁡x is undefined and the routine fails.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
Constraint: X≤1.0.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
The routine has been called with an argument greater than 1.0 in absolute value; arcsin⁡x is undefined and the routine returns zero.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

If δ and ε are the relative errors in the argument and result, respectively, then in principle
ε≃ x arcsin⁡x 1-x 2 ×δ .
That is, a relative error in the argument x is amplified by at least a factor x arcsin⁡x 1-x 2 in the result.
The equality should hold if δ is greater than the machine precision (δ is a result of data errors etc.) but if δ is produced simply by round-off error in the machine it is possible that rounding in internal calculations may lose an extra figure in the result.
This factor stays close to one except near x=1 where its behaviour is shown in the following graph.
Figure 1
For x close to unity, 1-x∼δ, the above analysis is no longer applicable owing to the fact that both argument and result are subject to finite bounds, (x≤1 and arcsin⁡x≤12 π). In this region ε∼δ; that is the result will have approximately half as many correct significant figures as the argument.
For x=1 the result will be correct to full machine precision.

8 Parallelism and Performance

S09AAF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s09aafe.f90)

10.2 Program Data

Program Data (s09aafe.d)

10.3 Program Results

Program Results (s09aafe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S09ABF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S09ABF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S09ABF returns the value of the inverse circular cosine, arccos⁡x, via the function name; the result is in the principal range 0,π.

2 Specification

FUNCTION S09ABF ( X, IFAIL)
REAL (KIND=nag_wp) S09ABF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S09ABF calculates an approximate value for the inverse circular cosine, arccos⁡x. It is based on the Chebyshev expansion
arcsin⁡x=x×y t=x∑′r=0 arTr t
where -1 2≤x≤ 1 2,   and  t=4 x 2-1.
For x 2≤ 12,  arccos⁡x= π 2-arcsin⁡x.
For -1≤x< -1 2,  arccos⁡x=π-arcsin⁡1-x 2.
For 1 2<x≤1,  arccos⁡x=arcsin⁡1-x 2.
For x>1,  arccos⁡x is undefined and the routine fails.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
Constraint: X≤1.0.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
S09ABF has been called with X>1.0, for which arccos is undefined. A zero result is returned.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

If δ and ε are the relative errors in the argument and the result, respectively, then in principle
ε≃ x arccos⁡x 1-x 2 ×δ .
The equality should hold if δ is greater than the machine precision (δ is due to data errors etc.), but if δ is due simply to round-off in the machine it is possible that rounding etc. in internal calculations may lose one extra figure.
The behaviour of the amplification factor x arccos⁡x 1-x 2 is shown in the graph below.
In the region of x=0 this factor tends to zero and the accuracy will be limited by the machine precision. For x close to one, 1-x∼δ, the above analysis is not applicable owing to the fact that both the argument and the result are bounded x≤1, 0≤arccos⁡x≤π.
In the region of x∼-1 we have ε∼δ, that is the result will have approximately half as many correct significant figures as the argument.
In the region x∼+1, we have that the absolute error in the result, E, is given by E∼δ, that is the result will have approximately half as many decimal places correct as there are correct figures in the argument.
Figure 1

8 Parallelism and Performance

S09ABF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s09abfe.f90)

10.2 Program Data

Program Data (s09abfe.d)

10.3 Program Results

Program Results (s09abfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S10AAF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S10AAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S10AAF returns a value for the hyperbolic tangent, tanh⁡x, via the function name.

2 Specification

FUNCTION S10AAF ( X, IFAIL)
REAL (KIND=nag_wp) S10AAF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S10AAF calculates an approximate value for the hyperbolic tangent of its argument, tanh⁡x.
For x≤1 it is based on the Chebyshev expansion
tanh⁡x=x×y t=x∑′r=0 arTr t
where -1≤x≤1,  -1≤t≤1,   and  t=2 x 2-1.
For 1<x<E 1 (see the Users' Note for your implementation for value of E 1)
tanh⁡x=e 2 x-1 e 2 x+1 .
For x≥E 1, tanh⁡x=sign⁡x to within the representation accuracy of the machine and so this approximation is used.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

None.

7 Accuracy

If δ and ε are the relative errors in the argument and the result respectively, then in principle,
ε≃ 2 x sinh⁡2 x δ .
That is, a relative error in the argument, x, is amplified by a factor approximately 2 x sinh⁡2 x , in the result.
The equality should hold if δ is greater than the machine precision (δ due to data errors etc.) but if δ is due simply to the round-off in the machine representation it is possible that an extra figure may be lost in internal calculation round-off.
The behaviour of the amplification factor is shown in the following graph:
Figure 1
It should be noted that this factor is always less than or equal to 1.0 and away from x=0 the accuracy will eventually be limited entirely by the precision of machine representation.

8 Parallelism and Performance

S10AAF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s10aafe.f90)

10.2 Program Data

Program Data (s10aafe.d)

10.3 Program Results

Program Results (s10aafe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S10ABF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S10ABF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S10ABF returns the value of the hyperbolic sine, sinh⁡x, via the function name.

2 Specification

FUNCTION S10ABF ( X, IFAIL)
REAL (KIND=nag_wp) S10ABF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S10ABF calculates an approximate value for the hyperbolic sine of its argument, sinh⁡x.
For x≤1 it uses the Chebyshev expansion
sinh⁡x=x×y t=x∑′r=0 arTr t
where t=2 x 2-1.
For 1<x≤E 1,  sinh⁡x=12 ex-e-x
where E 1 is a machine-dependent constant, details of which are given in the Users' Note for your implementation.
For x>E 1, the routine fails owing to the danger of setting overflow in calculating ex. The result returned for such calls is sinh sign⁡x E 1, i.e., it returns the result for the nearest valid argument.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
The routine has been called with an argument too large in absolute magnitude. There is a danger of setting overflow. The result is the value of sinh⁡x at the closest argument for which a valid call could be made. (See Section 3 and the Users' Note for your implementation.)
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

If δ and ε are the relative errors in the argument and result, respectively, then in principle
ε≃ x coth⁡x×δ.
That is the relative error in the argument, x, is amplified by a factor, approximately x coth⁡x. The equality should hold if δ is greater than the machine precision (δ is a result of data errors etc.) but, if δ is simply a result of round-off in the machine representation of x, then it is possible that an extra figure may be lost in internal calculation round-off.
The behaviour of the error amplification factor can be seen in the following graph:
Figure 1
It should be noted that for x≥2
ε∼xδ=Δ
where Δ is the absolute error in the argument.

8 Parallelism and Performance

S10ABF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s10abfe.f90)

10.2 Program Data

Program Data (s10abfe.d)

10.3 Program Results

Program Results (s10abfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S10ACF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S10ACF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S10ACF returns the value of the hyperbolic cosine, cosh⁡x, via the function name.

2 Specification

FUNCTION S10ACF ( X, IFAIL)
REAL (KIND=nag_wp) S10ACF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S10ACF calculates an approximate value for the hyperbolic cosine, cosh⁡x.
For x≤E 1,  cosh⁡x=12 ex+e-x.
For x>E 1, the routine fails owing to danger of setting overflow in calculating ex. The result returned for such calls is cosh⁡E 1, i.e., it returns the result for the nearest valid argument. The value of machine-dependent constant E 1 may be given in the Users' Note for your implementation.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
The routine has been called with an argument too large in absolute magnitude. There is a danger of overflow. The result returned is the value of cosh⁡x at the nearest valid argument.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

If δ and ε are the relative errors in the argument and result, respectively, then in principle
ε≃x tanh⁡x×δ.
That is, the relative error in the argument, x, is amplified by a factor, at least x tanh⁡x. The equality should hold if δ is greater than the machine precision (δ is due to data errors etc.) but if δ is simply a result of round-off in the machine representation of x then it is possible that an extra figure may be lost in internal calculation round-off.
The behaviour of the error amplification factor is shown by the following graph:
GnuplotProduced by GNUPLOT 4.6 patchlevel 3 0 2 4 6 8 10 −10 −5 0 5 10 ε/δ x gnuplot_plot_1
Figure 1
It should be noted that near x=0 where this amplification factor tends to zero the accuracy will be limited eventually by the machine precision. Also for x≥2
ε∼xδ=Δ
where Δ is the absolute error in the argument x.

8 Parallelism and Performance

S10ACF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s10acfe.f90)

10.2 Program Data

Program Data (s10acfe.d)

10.3 Program Results

Program Results (s10acfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S11AAF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S11AAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S11AAF returns the value of the inverse hyperbolic tangent, arctanh⁡x, via the function name.

2 Specification

FUNCTION S11AAF ( X, IFAIL)
REAL (KIND=nag_wp) S11AAF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S11AAF calculates an approximate value for the inverse hyperbolic tangent of its argument, arctanh⁡x.
For x 2≤12 it is based on the Chebyshev expansion
arctanh⁡x=x×y t=x∑′r=0 arTr t
where - 1 2≤x≤ 1 2,  -1≤t≤1,   and  t=4 x 2-1.
For 12<x 2<1, it uses
arctanh⁡x=12 ln 1+x 1-x .
For x≥1, the routine fails as arctanh⁡x is undefined.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
Constraint: X<1.0.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
The routine has been called with an argument greater than or equal to 1.0 in magnitude, for which arctanh is not defined. On soft failure, the result is returned as zero.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

If δ and ε are the relative errors in the argument and result, respectively, then in principle
ε≃ x 1-x 2 arctanh⁡x ×δ .
That is, the relative error in the argument, x, is amplified by at least a factor x 1-x 2 arctanh⁡x in the result. The equality should hold if δ is greater than the machine precision (δ due to data errors etc.) but if δ is simply due to round-off in the machine representation then it is possible that an extra figure may be lost in internal calculation round-off.
The behaviour of the amplification factor is shown in the following graph:
Figure 1
The factor is not significantly greater than one except for arguments close to x=1. However in the region where x is close to one, 1-x∼δ, the above analysis is inapplicable since x is bounded by definition, x<1. In this region where arctanh is tending to infinity we have
ε∼1/ln⁡δ
which implies an obvious, unavoidable serious loss of accuracy near x∼1, e.g., if x and 1 agree to 6 significant figures, the result for arctanh⁡x would be correct to at most about one figure.

8 Parallelism and Performance

S11AAF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s11aafe.f90)

10.2 Program Data

Program Data (s11aafe.d)

10.3 Program Results

Program Results (s11aafe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S11ABF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S11ABF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S11ABF returns the value of the inverse hyperbolic sine, arcsinh⁡x, via the function name.

2 Specification

FUNCTION S11ABF ( X, IFAIL)
REAL (KIND=nag_wp) S11ABF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S11ABF calculates an approximate value for the inverse hyperbolic sine of its argument, arcsinh⁡x.
For x≤1 it is based on the Chebyshev expansion
arcsinh⁡x=x×y t=x∑′r=0 crTr t,   where ​t=2 x 2-1.
For x>1 it uses the fact that
arcsinh⁡x=sign⁡x×ln x+x 2+1 .
This form is used directly for 1<x<10 k, where k=n/2+1, and the machine uses approximately n decimal place arithmetic.
For x≥10 k, x 2+1 is equal to x to within the accuracy of the machine and hence we can guard against premature overflow and, without loss of accuracy, calculate
arcsinh⁡x=sign⁡x×ln⁡2+ln x.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

None.

7 Accuracy

If δ and ε are the relative errors in the argument and the result, respectively, then in principle
ε≃ x 1+x 2 arcsinh⁡x δ .
That is, the relative error in the argument, x, is amplified by a factor at least x 1+x 2 arcsinh⁡x , in the result.
The equality should hold if δ is greater than the machine precision (δ due to data errors etc.) but if δ is simply due to round-off in the machine representation it is possible that an extra figure may be lost in internal calculation round-off.
The behaviour of the amplification factor is shown in the following graph:
Figure 1
It should be noted that this factor is always less than or equal to one. For large x we have the absolute error in the result, E, in principle, given by
E∼δ.
This means that eventually accuracy is limited by machine precision.

8 Parallelism and Performance

S11ABF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s11abfe.f90)

10.2 Program Data

Program Data (s11abfe.d)

10.3 Program Results

Program Results (s11abfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S11ACF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S11ACF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S11ACF returns the value of the inverse hyperbolic cosine, arccosh⁡x, via the function name. The result is in the principal positive branch.

2 Specification

FUNCTION S11ACF ( X, IFAIL)
REAL (KIND=nag_wp) S11ACF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S11ACF calculates an approximate value for the inverse hyperbolic cosine, arccosh⁡x. It is based on the relation
arccosh⁡x=ln x+x 2-1.
This form is used directly for 1<x<10 k, where k=n/2+1, and the machine uses approximately n decimal place arithmetic.
For x≥10 k, x 2-1 is equal to x to within the accuracy of the machine and hence we can guard against premature overflow and, without loss of accuracy, calculate
arccosh⁡x=ln⁡2+ln⁡x.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
Constraint: X≥1.0.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
The routine has been called with an argument less than 1.0, for which arccosh⁡x is not defined. The result returned is zero.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

If δ and ε are the relative errors in the argument and result respectively, then in principle
ε≃ x x 2-1 arccosh⁡x ×δ .
That is the relative error in the argument is amplified by a factor at least x x 2-1 arccosh⁡x in the result. The equality should apply if δ is greater than the machine precision (δ due to data errors etc.) but if δ is simply a result of round-off in the machine representation it is possible that an extra figure may be lost in internal calculation and round-off. The behaviour of the amplification factor is shown in the following graph:
Figure 1
It should be noted that for x>2 the factor is always less than 1.0. For large x we have the absolute error E in the result, in principle, given by
E∼δ.
This means that eventually accuracy is limited by machine precision. More significantly for x close to 1, x-1∼δ, the above analysis becomes inapplicable due to the fact that both function and argument are bounded, x≥1, arccosh⁡x≥0. In this region we have
E∼δ.
That is, there will be approximately half as many decimal places correct in the result as there were correct figures in the argument.

8 Parallelism and Performance

S11ACF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s11acfe.f90)

10.2 Program Data

Program Data (s11acfe.d)

10.3 Program Results

Program Results (s11acfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S13ACF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S13ACF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S13ACF returns the value of the cosine integral
Ci x=γ+ln⁡x+∫0 x cos⁡u-1 u du,  x>0
via the routine name where γ denotes Euler's constant.

2 Specification

FUNCTION S13ACF ( X, IFAIL)
REAL (KIND=nag_wp) S13ACF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S13ACF calculates an approximate value for Ci x.
For 0<x≤16 it is based on the Chebyshev expansion
Ci x=ln⁡x+∑r=0′arTr t,t=2 x 16 2-1.
For 16<x<xhi where the value of xhi is given in the Users' Note for your implementation,
Ci x=f x sin⁡x x-g x cos⁡x x 2
where f x=∑′r=0 frTr t and g x=∑′r=0 grTr t, t=2 16 x 2-1.
For x≥xhi, Ci x=0 to within the accuracy possible (see Section 7).

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
Constraint: X>0.0.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
The routine has been called with an argument less than or equal to zero for which the function is not defined. The result returned is zero.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

If E and ε are the absolute and relative errors in the result and δ is the relative error in the argument then in principle these are related by
E≃ δ cos⁡x and ​ ε≃ δ cos⁡x Ci x .
That is accuracy will be limited by machine precision near the origin and near the zeros of cos⁡x, but near the zeros of Ci x only absolute accuracy can be maintained.
The behaviour of this amplification is shown in Figure 1.
Figure 1
For large values of x, Ci x∼ sin⁡x x therefore ε∼δx cot⁡x and since δ is limited by the finite precision of the machine it becomes impossible to return results which have any relative accuracy. That is, when x≥1/δ we have that Ci x≤1/x∼E and hence is not significantly different from zero.
Hence xhi is chosen such that for values of x≥xhi, Ci x in principle would have values less than the machine precision and so is essentially zero.

8 Parallelism and Performance

S13ACF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s13acfe.f90)

10.2 Program Data

Program Data (s13acfe.d)

10.3 Program Results

Program Results (s13acfe.r)

GnuplotProduced by GNUPLOT 4.6 patchlevel 3 −1.5 −1 −0.5 0 0.5 1 0 5 10 15 20 25 Ci(x) x Example Program Returned Values for the Cosine Integral Ci(x) gnuplot_plot_1
S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S13ADF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S13ADF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S13ADF returns the value of the sine integral
Si x=∫0 x sin⁡u u du,
via the function name.

2 Specification

FUNCTION S13ADF ( X, IFAIL)
REAL (KIND=nag_wp) S13ADF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S13ADF calculates an approximate value for Si x.
For x≤16.0 it is based on the Chebyshev expansion
Si x=x∑r=0′arTr t,t=2 x 16 2-1.
For 16<x<xhi, where xhi is an implementation-dependent number,
Si x=sign x π 2-f x cos⁡x x-g x sin⁡x x 2
where f x=∑′r=0 frTr t and g x=∑′r=0 grTr t, t=2 16 x 2-1.
For x≥xhi, Si x=12 π sign⁡x to within machine precision.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

There are no failure exits from S13ADF. The argument IFAIL has been included for consistency with other routines in this chapter.

7 Accuracy

If δ and ε are the relative errors in the argument and result, respectively, then in principle
ε≃ δ sin⁡x Si x .
The equality may hold if δ is greater than the machine precision (δ due to data errors etc.) but if δ is simply due to round-off in the machine representation, then since the factor relating δ to ε is always less than one, the accuracy will be limited by machine precision.

8 Parallelism and Performance

S13ADF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s13adfe.f90)

10.2 Program Data

Program Data (s13adfe.d)

10.3 Program Results

Program Results (s13adfe.r)

GnuplotProduced by GNUPLOT 4.6 patchlevel 3 −2 −1.5 −1 −0.5 0 0.5 1 1.5 2 −10 −5 0 5 10 Si(x) x Example Program Returned Values for the Sine Integral Si(x) gnuplot_plot_1
S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S14AAF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S14AAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S14AAF returns the value of the gamma function Γ x, via the function name.

2 Specification

FUNCTION S14AAF ( X, IFAIL)
REAL (KIND=nag_wp) S14AAF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S14AAF evaluates an approximation to the gamma function Γ x. The routine is based on the Chebyshev expansion:
Γ 1+u=∑r=0′arTr t,   where ​ 0≤u<1,t=2 u-1,
and uses the property Γ 1+x=xΓ x. If x=N+1+u where N is integral and 0≤u<1 then it follows that:
  • for N>0,  Γ x=x-1x-2⋯x-N Γ 1+u,
  • for N=0,  Γ x=Γ 1+u,
  • for N<0,  Γ x= Γ 1+u x x+1x+2⋯x-N-1 .
There are four possible failures for this routine:
(i) | if x is too large, there is a danger of overflow since Γ x could become too large to be represented in the machine;
(ii) | if x is too large and negative, there is a danger of underflow;
(iii) | if x is equal to a negative integer, Γ x would overflow since it has poles at such points;
(iv) | if x is too near zero, there is again the danger of overflow on some machines. For small x, Γ x≃1/x , and on some machines there exists a range of nonzero but small values of x for which 1/x is larger than the greatest representable value.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
Constraint: X must not be zero or a negative integer.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
The argument is too large. On soft failure the routine returns the approximate value of Γ x at the nearest valid argument.
IFAIL=2
The argument is too large and negative. On soft failure the routine returns zero.
IFAIL=3
The argument is too close to zero. On soft failure the routine returns the approximate value of Γ x at the nearest valid argument.
IFAIL=4
The argument is a negative integer, at which value Γ x is infinite. On soft failure the routine returns a large positive value.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Let δ and ε be the relative errors in the argument and the result respectively. If δ is somewhat larger than the machine precision (i.e., is due to data errors etc.), then ε and δ are approximately related by:
ε≃xΨ x δ
(provided ε is also greater than the representation error). Here Ψ x is the digamma function Γ′x Γ x . Figure 1 shows the behaviour of the error amplification factor xΨ x.
If δ is of the same order as machine precision, then rounding errors could make ε slightly larger than the above relation predicts.
There is clearly a severe, but unavoidable, loss of accuracy for arguments close to the poles of Γ x at negative integers. However relative accuracy is preserved near the pole at x=0 right up to the point of failure arising from the danger of overflow.
Also accuracy will necessarily be lost as x becomes large since in this region
ε≃δx ln⁡x.
However since Γ x increases rapidly with x, the routine must fail due to the danger of overflow before this loss of accuracy is too great. (For example, for x=20, the amplification factor ≃60.)
Figure 1

8 Parallelism and Performance

S14AAF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s14aafe.f90)

10.2 Program Data

Program Data (s14aafe.d)

10.3 Program Results

Program Results (s14aafe.r)

GnuplotProduced by GNUPLOT 4.6 patchlevel 3 −4 −2 0 2 4 −4 −3 −2 −1 0 1 2 3 4 Γ(x) x Example Program Returned Values for the Gamma Function Γ(x) gnuplot_plot_1
S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S14ABF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S14ABF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S14ABF returns the value of the logarithm of the gamma function, ln⁡Γ x, via the function name.

2 Specification

FUNCTION S14ABF ( X, IFAIL)
REAL (KIND=nag_wp) S14ABF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S14ABF calculates an approximate value for ln⁡Γ x. It is based on rational Chebyshev expansions.
Denote by R n,m i x=Pni x/Qmi x a ratio of polynomials of degree n in the numerator and m in the denominator. Then:
  • for 0<x≤1/2,
    ln⁡Γ x ≈ -ln x + x R n,m 1 x+1 ;
  • for 1/2<x≤3/2,
    ln⁡Γ x ≈ x-1 R n,m 1 x ;
  • for 3/2<x≤4,
    ln⁡Γ x ≈ x-2 R n,m 2 x;
  • for 4<x≤12,
    ln⁡Γ x ≈ R n,m 3 x ;
  • and for 12<x,
    ln⁡Γ x ≈ x-12 ln x - x + ln 2π + 1 x R n,m 4 1/x 2 . (1)
For each expansion, the specific values of n and m are selected to be minimal such that the maximum relative error in the expansion is of the order 10-d, where d is the maximum number of decimal digits that can be accurately represented for the particular implementation (see X02BEF).
Let ε denote machine precision and let xhuge denote the largest positive model number (see X02ALF). For x<0.0 the value ln⁡Γ x is not defined; S14ABF returns zero and exits with IFAIL=1. It also exits with IFAIL=1 when x=0.0, and in this case the value xhuge is returned. For x in the interval 0.0,ε, the function ln⁡Γ x=-ln x to machine accuracy.
Now denote by xbig the largest allowable argument for ln⁡Γ x on the machine. For xbig 1/4<x≤xbig the R n,m 4 1/x 2 term in Equation (1) is negligible. For x>xbig there is a danger of setting overflow, and so S14ABF exits with IFAIL=2 and returns xhuge. The value of xbig is given in the Users' Note for your implementation.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Cody W J and Hillstrom K E (1967) Chebyshev approximations for the natural logarithm of the gamma function Math.Comp. 21 198–203

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
Constraint: X>0.0.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, X≤0.0. If X<0.0 the function is undefined; on soft failure, the function value returned is zero. If X=0.0 and soft failure is selected, the function value returned is the largest machine number (see X02ALF).
IFAIL=2
On entry, X>xbig (see Section 3). On soft failure, the function value returned is the largest machine number (see X02ALF).
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Let δ and ε be the relative errors in the argument and result respectively, and E be the absolute error in the result.
If δ is somewhat larger than machine precision, then
E≃ x×Ψ x δ   and   ε≃ x×Ψ x ln⁡Γ x δ
where Ψ x is the digamma function Γ′x Γ x . Figure 1 and Figure 2 show the behaviour of these error amplification factors.
Figure 1
Figure 2
These show that relative error can be controlled, since except near x=1​ or ​2 relative error is attenuated by the function or at least is not greatly amplified.
For large x, ε≃1+ 1 ln⁡x δ and for small x, ε≃ 1 ln⁡x δ.
The function ln⁡Γ x has zeros at x=1 and 2 and hence relative accuracy is not maintainable near those points. However absolute accuracy can still be provided near those zeros as is shown above.
If however, δ is of the order of machine precision, then rounding errors in the routine's internal arithmetic may result in errors which are slightly larger than those predicted by the equalities. It should be noted that even in areas where strong attenuation of errors is predicted the relative precision is bounded by the effective machine precision.

8 Parallelism and Performance

S14ABF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s14abfe.f90)

10.2 Program Data

Program Data (s14abfe.d)

10.3 Program Results

Program Results (s14abfe.r)

GnuplotProduced by GNUPLOT 4.6 patchlevel 3 0 2 4 6 8 0 1 2 3 4 5 6 7 8 lnΓ(x) x Example Program Returned Values for the Logarithm of the Gamma Function, lnΓ(x) gnuplot_plot_1
S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S14ACF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S14ACF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S14ACF returns a value of the function ψ x-ln⁡x, where ψ is the psi function ψ x= d dx ln⁡Γ x= Γ′x Γ x .

2 Specification

FUNCTION S14ACF ( X, IFAIL)
REAL (KIND=nag_wp) S14ACF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S14ACF returns a value of the function ψ x-ln⁡x. The psi function is computed without the logarithmic term so that when x is large, sums or differences of psi functions may be computed without unnecessary loss of precision, by analytically combining the logarithmic terms. For example, the difference d=ψ x+12-ψ x has an asymptotic behaviour for large x given by d∼ln x+12-ln⁡x+O 1 x 2∼ln 1+ 1 2 x ∼ 1 2 x .
Computing d directly would amount to subtracting two large numbers which are close to ln x+12 and ln⁡x to produce a small number close to 1 2 x , resulting in a loss of significant digits. However, using this routine to compute f x=ψ x-ln⁡x, we can compute d=f x+12-f x+ln 1+1 2 x , and the dominant logarithmic term may be computed accurately from its power series when x is large. Thus we avoid the unnecessary loss of precision.
The routine is derived from the routine PSIFN in Amos (1983).

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Amos D E (1983) Algorithm 610: A portable FORTRAN subroutine for derivatives of the psi function ACM Trans. Math. Software 9 494–502

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
Constraint: X>0.0.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, X≤0.0. S14ACF returns the value zero.
IFAIL=2
No result is computed because underflow is likely. The value of X is too large. S14ACF returns the value zero.
IFAIL=3
No result is computed because overflow is likely. The value of X is too small. S14ACF returns the value zero.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

All constants in S14ACF are given to approximately 18 digits of precision. Calling the number of digits of precision in the floating-point arithmetic being used t, then clearly the maximum number of correct digits in the results obtained is limited by p=min t,18.
With the above proviso, results returned by this routine should be accurate almost to full precision, except at points close to the zero of ψ x, x≃1.461632, where only absolute rather than relative accuracy can be obtained.

8 Parallelism and Performance

S14ACF is not threaded in any implementation.

9 Further Comments

None.

10 Example

The example program reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s14acfe.f90)

10.2 Program Data

Program Data (s14acfe.d)

10.3 Program Results

Program Results (s14acfe.r)

GnuplotProduced by GNUPLOT 4.6 patchlevel 3 −7 −6 −5 −4 −3 −2 −1 0 0 1 2 3 4 5 6 7 8 ψ(x)−ln x x Example Program Returns a Value of the Function ψ(x)−ln x gnuplot_plot_1
S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S14ADF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S14ADF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S14ADF returns a sequence of values of scaled derivatives of the psi function ψ x (also known as the digamma function).

2 Specification

SUBROUTINE S14ADF ( X, N, M, ANS, IFAIL)
INTEGER | N, M, IFAIL
REAL (KIND=nag_wp) | X, ANS(M)

3 Description

S14ADF computes m values of the function
w k,x=-1 k+1ψ k x k! ,
for x>0, k=n, n+1,…,n+m-1, where ψ is the psi function
ψ x=d dx ln⁡Γ x=Γ′x Γ x ,
and ψ k denotes the kth derivative of ψ.
The routine is derived from the routine PSIFN in Amos (1983). The basic method of evaluation of w k,x is the asymptotic series
w k,x∼ε k,x+1 2 x k+1 +1 xk∑j=1∞B 2 j 2 j+k-1! 2 j!k!x 2 j
for large x greater than a machine-dependent value xmin, followed by backward recurrence using
w k,x=w k,x+1+x-k-1
for smaller values of x, where ε k,x=-ln⁡x when k=0, ε k,x= 1 k xk when k>0, and B 2 j, j=1,2,…, are the Bernoulli numbers.
When k is large, the above procedure may be inefficient, and the expansion
w k,x=∑j=1∞1 x+j k+1,
which converges rapidly for large k, is used instead.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Amos D E (1983) Algorithm 610: A portable FORTRAN subroutine for derivatives of the psi function ACM Trans. Math. Software 9 494–502

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
Constraint: X>0.0.
2:   N – INTEGERInput
On entry: the index of the first member n of the sequence of functions.
Constraint: N≥0.
3:   M – INTEGERInput
On entry: the number of members m required in the sequence w k,x, for k=n,…,n+m-1.
Constraint: M≥1.
4:   ANS M – REAL (KIND=nag_wp) arrayOutput
On exit: the first m elements of ANS contain the required values w k,x, for k=n,…,n+m-1.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, X≤0.0.
IFAIL=2
On entry, N<0.
IFAIL=3
On entry, M<1.
IFAIL=4
No results are returned because underflow is likely. Either X or N+M-1 is too large. If possible, reduce the value of M and call S14ADF again.
IFAIL=5
No results are returned because overflow is likely. Either X is too small, or N+M-1 is too large. If possible, reduce the value of M and call S14ADF again.
IFAIL=6
No results are returned because there is not enough internal workspace to continue computation. N+M-1 may be too large. If possible, reduce the value of M and call S14ADF again.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

All constants in S14ADF are given to approximately 18 digits of precision. Calling the number of digits of precision in the floating-point arithmetic being used t, then clearly the maximum number of correct digits in the results obtained is limited by p=min t,18. Empirical tests of S14ADF, taking values of x in the range 0.0<x<50.0, and n in the range 1≤n≤50, have shown that the maximum relative error is a loss of approximately two decimal places of precision. Tests with n=0, i.e., testing the function -ψ x, have shown somewhat better accuracy, except at points close to the zero of ψ x, x≃1.461632, where only absolute accuracy can be obtained.

8 Parallelism and Performance

S14ADF is not threaded in any implementation.

9 Further Comments

The time taken for a call of S14ADF is approximately proportional to m, plus a constant. In general, it is much cheaper to call S14ADF with m greater than 1 to evaluate the function w k,x, for k=n,…,n+m-1, rather than to make m separate calls of S14ADF.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s14adfe.f90)

10.2 Program Data

Program Data (s14adfe.d)

10.3 Program Results

Program Results (s14adfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S14AEF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S14AEF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S14AEF returns the value of the kth derivative of the psi function ψ x for real x and k=0,1,…,6, via the function name.

2 Specification

FUNCTION S14AEF ( X, K, IFAIL)
REAL (KIND=nag_wp) S14AEF
INTEGER | K, IFAIL
REAL (KIND=nag_wp) | X

3 Description

S14AEF evaluates an approximation to the kth derivative of the psi function ψ x given by
ψ k x=dk d xk ψ x=dk d xk d dx loge⁡Γ x ,
where x is real with x≠0,-1,-2,… and k=0,1,…,6. For negative noninteger values of x, the recurrence relationship
ψ k x+1=ψ k x+dk d xk 1 x
is used. The value of -1 k+1ψ k x k! is obtained by a call to S14ADF, which is based on the routine PSIFN in Amos (1983).
Note that ψ k x is also known as the polygamma function. Specifically, ψ 0 x is often referred to as the digamma function and ψ 1 x as the trigamma function in the literature. Further details can be found in Abramowitz and Stegun (1972).

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Amos D E (1983) Algorithm 610: A portable FORTRAN subroutine for derivatives of the psi function ACM Trans. Math. Software 9 494–502

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
Constraint: X must not be ‘too close’ (see Section 6) to a non-positive integer.
2:   K – INTEGERInput
On entry: the function ψ k x to be evaluated.
Constraint: 0≤K≤6.
3:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | K<0,
or | K>6,
or | X is ‘too close’ to a non-positive integer. That is, abs X - nint X < machine precision × nint abs X .
IFAIL=2
The evaluation has been abandoned due to the likelihood of underflow. The result is returned as zero.
IFAIL=3
The evaluation has been abandoned due to the likelihood of overflow. The result is returned as zero.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

All constants in S14ADF are given to approximately 18 digits of precision. If t denotes the number of digits of precision in the floating-point arithmetic being used, then clearly the maximum number in the results obtained is limited by p=min t,18. Empirical tests by Amos (1983) have shown that the maximum relative error is a loss of approximately two decimal places of precision. Further tests with the function -ψ 0 x have shown somewhat improved accuracy, except at points near the positive zero of ψ 0 x at x=1.46…, where only absolute accuracy can be obtained.

8 Parallelism and Performance

S14AEF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example evaluates ψ 2 x at x=2.5, and prints the results.

10.1 Program Text

Program Text (s14aefe.f90)

10.2 Program Data

Program Data (s14aefe.d)

10.3 Program Results

Program Results (s14aefe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S14AFF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S14AFF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S14AFF returns the value of the kth derivative of the psi function ψ z for complex z and k=0,1,…,4, via the function name.

2 Specification

FUNCTION S14AFF ( Z, K, IFAIL)
COMPLEX (KIND=nag_wp) S14AFF
INTEGER | K, IFAIL
COMPLEX (KIND=nag_wp) | Z

3 Description

S14AFF evaluates an approximation to the kth derivative of the psi function ψ z given by
ψ k z=dk d zk ψ z=dk d zk d dz loge⁡Γ z ,
where z=x+iy is complex provided y≠0 and k=0,1,…,4. If y=0, z is real and thus ψ k z is singular when z=0,-1,-2,….
Note that ψ k z is also known as the polygamma function. Specifically, ψ 0 z is often referred to as the digamma function and ψ 1 z as the trigamma function in the literature. Further details can be found in Abramowitz and Stegun (1972).
S14AFF is based on a modification of the method proposed by Kölbig (1972).
To obtain the value of ψ k z when z is real, S14AEF can be used.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Kölbig K S (1972) Programs for computing the logarithm of the gamma function, and the digamma function, for complex arguments Comp. Phys. Comm. 4 221–226

5 Arguments

1:   Z – COMPLEX (KIND=nag_wp)Input
On entry: the argument z of the function.
Constraint: Re(Z) must not be ‘too close’ (see Section 6) to a non-positive integer when Im(Z)=0.0.
2:   K – INTEGERInput
On entry: the function ψ k z to be evaluated.
Constraint: 0≤K≤4.
3:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | K<0,
or | K>4,
or | Re Z is ‘too close’ to a non-positive integer when Im Z=0.0. That is, abs Re Z - nint Re Z < machine precision × nint abs Re Z .
IFAIL=2
The evaluation has been abandoned due to the likelihood of overflow. The result is returned as zero.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Empirical tests have shown that the maximum relative error is a loss of approximately two decimal places of precision.

8 Parallelism and Performance

S14AFF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example evaluates the psi (trigamma) function ψ 1 z at z=-1.5+2.5 i, and prints the results.

10.1 Program Text

Program Text (s14affe.f90)

10.2 Program Data

Program Data (s14affe.d)

10.3 Program Results

Program Results (s14affe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S14AGF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S14AGF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S14AGF returns the value of the logarithm of the gamma function ln⁡Γ z for complex z, via the function name.

2 Specification

FUNCTION S14AGF ( Z, IFAIL)
COMPLEX (KIND=nag_wp) S14AGF
INTEGER | IFAIL
COMPLEX (KIND=nag_wp) | Z

3 Description

S14AGF evaluates an approximation to the logarithm of the gamma function ln⁡Γ z defined for Re z>0 by
ln⁡Γ z=ln⁡∫0∞e-tt z-1 dt
where z=x+iy is complex. It is extended to the rest of the complex plane by analytic continuation unless y=0, in which case z is real and each of the points z=0,-1,-2,… is a singularity and a branch point.
S14AGF is based on the method proposed by Kölbig (1972) in which the value of ln⁡Γ z is computed in the different regions of the z plane by means of the formulae
ln⁡Γ z = z-12 ln⁡z-z+12 ln⁡2 π+z∑k=1 K B 2 k 2 k 2 k-1 z-2 k+RK z if ​x≥x 0≥0, = ln⁡Γ z+n-ln⁡∏ν=0 n-1 z+ν if ​x 0>x≥0, = ln⁡π-ln⁡Γ 1-z-ln sin⁡πz if ​x<0,
where n=x 0-x, B 2 k are Bernoulli numbers (see Abramowitz and Stegun (1972)) and x is the largest integer ≤x. Note that care is taken to ensure that the imaginary part is computed correctly, and not merely modulo 2 π.
The routine uses the values K=10 and x 0=7. The remainder term RK z is discussed in Section 7.
To obtain the value of ln⁡Γ z when z is real and positive, S14ABF can be used.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Kölbig K S (1972) Programs for computing the logarithm of the gamma function, and the digamma function, for complex arguments Comp. Phys. Comm. 4 221–226

5 Arguments

1:   Z – COMPLEX (KIND=nag_wp)Input
On entry: the argument z of the function.
Constraint: Re(Z) must not be ‘too close’ (see Section 6) to a non-positive integer when Im(Z)=0.0.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, Re Z is ‘too close’ to a non-positive integer when Im Z=0.0. That is, abs Re Z-nint Re Z<machine precision×nint abs Re Z.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The remainder term RK z satisfies the following error bound:
RK z ≤ B 2 K 2 K-1 z 1-2 K ≤ B 2 K 2 K-1 x 1-2 K if ​x≥0.
Thus R 10 7<2.5×10-15 and hence in theory the routine is capable of achieving an accuracy of approximately 15 significant digits.

8 Parallelism and Performance

S14AGF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example evaluates the logarithm of the gamma function ln⁡Γ z at z=-1.5+2.5 i, and prints the results.

10.1 Program Text

Program Text (s14agfe.f90)

10.2 Program Data

Program Data (s14agfe.d)

10.3 Program Results

Program Results (s14agfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S14AHF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S14AHF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S14AHF returns the value of ln⁡G x, the scaled logarithm of the gamma function Γ x, via the function name.

2 Specification

FUNCTION S14AHF ( X, IFAIL)
REAL (KIND=nag_wp) S14AHF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S14AHF calculates an approximate value for ln⁡G x, where G x=Γ x+1/xe x. This is a variant of the ln⁡Γ x function (see also S14ABF), which avoids rounding problems for very large arguments by computing ln⁡Γ x with the Stirling approximation factored out.
For 0<x<15, ln⁡G x=ln⁡Γ x+1-x⁢ln⁡x+x;
and for 15≤x, ln⁡G x=12 ln⁡x+ln 2 π+1 x R 1/x 2, where R is a suitable Remez approximation.
For x≤0.0, the value ln⁡G x is undefined; S14AHF returns zero and exits with IFAIL=1.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
Constraint: X>0.0.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, X≤0.0. On soft failure, the function value returned is zero.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

S14AHF has been designed to produce full relative accuracy for all input arguments. Empirical results obtained by comparing with multiprecision software confirm this.

8 Parallelism and Performance

S14AHF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s14ahfe.f90)

10.2 Program Data

Program Data (s14ahfe.d)

10.3 Program Results

Program Results (s14ahfe.r)

GnuplotProduced by GNUPLOT 4.6 patchlevel 3 0.2 0.4 0.6 0.8 1 1.2 1.4 1.6 1.8 2 0 1 2 3 4 5 6 7 8 lnG(x) x Example Program Returns the Value of lnG(x), the Scaled Logarithm of the Gamma Function Γ(x) gnuplot_plot_1
S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S14CBF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S14CBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S14CBF returns the value of the logarithm of the beta function, ln⁡B a,b, via the routine name.

2 Specification

FUNCTION S14CBF ( A, B, IFAIL)
REAL (KIND=nag_wp) S14CBF
INTEGER | IFAIL
REAL (KIND=nag_wp) | A, B

3 Description

S14CBF calculates values for ln⁡B a,b where B is the beta function given by
B a,b = ∫ 0 1 t a-1 1-t b-1 dt
or equivalently
B a,b = Γ a Γ b Γ a+b
and Γ x is the gamma function. Note that the beta function is symmetric, so that B a,b=B b,a.
In order to efficiently obtain accurate results several methods are used depending on the parameters a and b.
Let a 0=min a,b and b 0=max a,b. Then:
for a 0≥8,
ln⁡B = 0.5 ln⁡ 2 π -0.5 ln b 0 + Δ a 0 + Δ b 0 - Δ a 0+b 0 - u - v ;
where
  • Δ a 0 = ln⁡ Γ a 0 - a 0-0.5 ln⁡a 0 + a 0-0.5 ln 2 π ,
  • u = -a 0-0.5 ln a 0 a 0 + b 0  and
  • v = b 0 ln 1+ a 0 b 0 .
for a 0<1,
  • for b 0≥8,
    ln⁡B = ln⁡Γ a 0 + ln⁡ Γ b 0 Γ a 0 + b 0 ;
  • for b 0<8,
    ln⁡B = ln⁡Γ a 0 + ln⁡Γ b 0 - ln⁡Γ a 0 + b 0 ;
for 2<a 0<8,  a 0 is reduced to the interval 1,2 by B a,b=a 0-1a 0+b 0-1 B a 0-1,b 0;
for 1≤a 0≤2,
  • for b 0≥8,
    ln⁡B = ln⁡Γ a 0 + ln⁡ Γ b 0 Γ a 0 + b 0 ;
  • for 2<b 0<8, b 0 is reduced to the interval 1,2;
  • for b 0≤2,
    ln⁡B = ln⁡Γ a 0 + ln⁡Γ b 0 - ln⁡Γ a 0 + b 0 .
S14CBF is derived from BETALN in DiDonato and Morris (1992).

4 References

DiDonato A R and Morris A H (1992) Algorithm 708: Significant digit computation of the incomplete beta function ratios ACM Trans. Math. Software 18 360–373

5 Arguments

1:   A – REAL (KIND=nag_wp)Input
On entry: the argument a of the function.
Constraint: A>0.0.
2:   B – REAL (KIND=nag_wp)Input
On entry: the argument b of the function.
Constraint: B>0.0.
3:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, A=value.
Constraint: A>0.0.
On entry, B=value.
Constraint: B>0.0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

S14CBF should produce full relative accuracy for all input arguments.

8 Parallelism and Performance

S14CBF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the arguments a and b from a file, evaluates the function and prints the results.

10.1 Program Text

Program Text (s14cbfe.f90)

10.2 Program Data

Program Data (s14cbfe.d)

10.3 Program Results

Program Results (s14cbfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S14CCF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S14CCF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S14CCF computes values for the incomplete beta function Ix a,b and its complement 1-Ix a,b.

2 Specification

SUBROUTINE S14CCF ( A, B, X, W, W1, IFAIL)
INTEGER | IFAIL
REAL (KIND=nag_wp) | A, B, X, W, W1

3 Description

S14CCF evaluates the incomplete beta function and its complement in the normalized form
Ix a,b = 1 B a,b ∫ 0 x t a-1 1-t b-1 dt 1–Ix a,b = Iy b,a , where ​ y=1-x ,
with
  • 0≤x≤1,
  • a≥0 and b≥0,
  • and the beta function B a,b is defined as B a,b = ∫01 t a-1 1-t b-1 dt = Γ a Γ b Γ a+b where Γ y is the gamma function.
Several methods are used to evaluate the functions depending on the arguments a, b and x. The methods include Wise's asymptotic expansion (see Wise (1950)) when a>b, continued fraction derived by DiDonato and Morris (1992) when a, b>1, and power series when b≤1 or b×x≤0.7. When both a and b are large, specifically a, b≥15, the DiDonato and Morris (1992) asymptotic expansion is employed for greater efficiency.
Once either Ix a,b or Iy b,a is computed, the other is obtained by subtraction from 1. In order to avoid loss of relative precision in this subtraction, the smaller of Ix a,b and Iy b,a is computed first.
S14CCF is derived from BRATIO in DiDonato and Morris (1992).

4 References

DiDonato A R and Morris A H (1992) Algorithm 708: Significant digit computation of the incomplete beta function ratios ACM Trans. Math. Software 18 360–373
Wise M E (1950) The incomplete beta function as a contour integral and a quickly converging series for its inverse Biometrika 37 208–218

5 Arguments

1:   A – REAL (KIND=nag_wp)Input
On entry: the argument a of the function.
Constraint: A≥0.0.
2:   B – REAL (KIND=nag_wp)Input
On entry: the argument b of the function.
Constraints:
  • B≥0.0;
  • either B≠0.0 or A≠0.0.
3:   X – REAL (KIND=nag_wp)Input
On entry: x, upper limit of integration.
Constraints:
  • 0.0≤X≤1.0;
  • either X≠0.0 or A≠0.0;
  • either 1-X≠0.0 or B≠0.0.
4:   W – REAL (KIND=nag_wp)Output
On exit: the value of the incomplete beta function Ix a,b evaluated from zero to x.
5:   W1 – REAL (KIND=nag_wp)Output
On exit: the value of the complement of the incomplete beta function 1-Ix a,b, i.e., the incomplete beta function evaluated from x to one.
6:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, A=value.
Constraint: A≥0.0.
On entry, B=value.
Constraint: B≥0.0.
IFAIL=2
On entry, A and B were zero.
Constraint: A or B must be nonzero.
IFAIL=3
On entry, X=value.
Constraint: 0.0≤X≤1.0.
IFAIL=4
On entry, X and A were zero.
Constraint: X or A must be nonzero.
IFAIL=5
On entry, 1.0-X and B were zero.
Constraint: 1.0-X or B must be nonzero.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

S14CCF is designed to maintain relative accuracy for all arguments. For very tiny results (of the order of machine precision or less) some relative accuracy may be lost – loss of three or four decimal places has been observed in experiments. For other arguments full relative accuracy may be expected.

8 Parallelism and Performance

S14CCF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the arguments a and b from a file, evaluates the function and its complement for 10 different values of x and prints the results.

10.1 Program Text

Program Text (s14ccfe.f90)

10.2 Program Data

Program Data (s14ccfe.d)

10.3 Program Results

Program Results (s14ccfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S15ABF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S15ABF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S15ABF returns the value of the cumulative Normal distribution function, P x, via the function name.

2 Specification

FUNCTION S15ABF ( X, IFAIL)
REAL (KIND=nag_wp) S15ABF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S15ABF evaluates an approximate value for the cumulative Normal distribution function
P x=1 2 π∫-∞x e-u 2/2 du.
The routine is based on the fact that
P x=12 erfc-x 2
and it calls S15ADF to obtain a value of erfc for the appropriate argument.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

There are no failure exits from this routine. The argument IFAIL is included for consistency with other routines in this chapter.

7 Accuracy

Because of its close relationship with erfc, the accuracy of this routine is very similar to that in S15ADF. If ε and δ are the relative errors in result and argument, respectively, they are in principle related by
ε≃ x e -12 x 2 2 π P x δ
so that the relative error in the argument, x, is amplified by a factor, x e-12 x 2 2 π P x , in the result.
For x small and for x positive this factor is always less than one and accuracy is mainly limited by machine precision.
For large negative x the factor behaves like ∼x 2 and hence to a certain extent relative accuracy is unavoidably lost.
However the absolute error in the result, E, is given by
E≃ x e -12 x 2 2 π δ
so absolute accuracy can be guaranteed for all x.

8 Parallelism and Performance

S15ABF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s15abfe.f90)

10.2 Program Data

Program Data (s15abfe.d)

10.3 Program Results

Program Results (s15abfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S15ACF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S15ACF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S15ACF returns the value of the complement of the cumulative Normal distribution function, Q x, via the function name.

2 Specification

FUNCTION S15ACF ( X, IFAIL)
REAL (KIND=nag_wp) S15ACF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S15ACF evaluates an approximate value for the complement of the cumulative Normal distribution function
Q x=1 2 π∫x∞e-u 2/2 du.
The routine is based on the fact that
Q x=12 erfc x 2
and it calls S15ADF to obtain the necessary value of erfc, the complementary error function.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

There are no failure exits from this routine. The argument IFAIL is included for consistency with other routines in this chapter.

7 Accuracy

Because of its close relationship with erfc the accuracy of this routine is very similar to that in S15ADF. If ε and δ are the relative errors in result and argument, respectively, then in principle they are related by
ε≃ x e -x 2/2 2 π Q x δ .
For x negative or small positive this factor is always less than one and accuracy is mainly limited by machine precision. For large positive x we find ε∼x 2 δ and hence to a certain extent relative accuracy is unavoidably lost. However the absolute error in the result, E, is given by
E≃ x e -x 2/2 2 π δ
and since this factor is always less than one absolute accuracy can be guaranteed for all x.

8 Parallelism and Performance

S15ACF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s15acfe.f90)

10.2 Program Data

Program Data (s15acfe.d)

10.3 Program Results

Program Results (s15acfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S15ADF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S15ADF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S15ADF returns the value of the complementary error function, erfc x, via the function name.

2 Specification

FUNCTION S15ADF ( X, IFAIL)
REAL (KIND=nag_wp) S15ADF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S15ADF calculates an approximate value for the complement of the error function
erfc x=2 π∫x∞e-t 2 dt=1-erf x.
Let x^ be the root of the equation erfc x-erf x=0 (then x^≈0.46875). For x≤x^ the value of erfc x is based on the following rational Chebyshev expansion for erf x:
erf x≈x R ℓ,m x 2,
where R ℓ,m denotes a rational function of degree ℓ in the numerator and m in the denominator.
For x>x^ the value of erfc x is based on a rational Chebyshev expansion for erfc x: for x^<x≤4 the value is based on the expansion
erfc x≈e x 2 R ℓ,m x;
and for x>4 it is based on the expansion
erfc x≈e x 2 x 1 π+1 x 2 R ℓ,m 1/x 2.
For each expansion, the specific values of ℓ and m are selected to be minimal such that the maximum relative error in the expansion is of the order 10-d, where d is the maximum number of decimal digits that can be accurately represented for the particular implementation (see X02BEF).
For x≥xhi there is a danger of setting underflow in erfc x (the value of xhi is given in the Users' Note for your implementation). For x≥xhi, S15ADF returns erfc x=0; for x≤-xhi it returns erfc x=2.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Cody W J (1969) Rational Chebyshev approximations for the error function Math.Comp. 23 631–637

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

There are no failure exits from S15ADF. The argument IFAIL has been included for consistency with other routines in this chapter.

7 Accuracy

If δ and ε are relative errors in the argument and result, respectively, then in principle
ε≃ 2 x e -x 2 π erfc x δ .
That is, the relative error in the argument, x, is amplified by a factor 2 x e-x 2 π erfc x in the result.
The behaviour of this factor is shown in Figure 1.
Figure 1
It should be noted that near x=0 this factor behaves as 2 x π and hence the accuracy is largely determined by the machine precision. Also for large negative x, where the factor is ∼ x e-x 2 π , accuracy is mainly limited by machine precision. However, for large positive x, the factor becomes ∼2 x 2 and to an extent relative accuracy is necessarily lost. The absolute accuracy E is given by
E≃2 x e-x 2 π δ
so absolute accuracy is guaranteed for all x.

8 Parallelism and Performance

S15ADF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s15adfe.f90)

10.2 Program Data

Program Data (s15adfe.d)

10.3 Program Results

Program Results (s15adfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S15AEF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S15AEF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S15AEF returns the value of the error function erf x, via the function name.

2 Specification

FUNCTION S15AEF ( X, IFAIL)
REAL (KIND=nag_wp) S15AEF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S15AEF calculates an approximate value for the error function
erf x=2 π∫0 x e-t 2 dt=1-erfc x.
Let x^ be the root of the equation erfc x-erf x=0 (then x^≈0.46875). For x≤x^ the value of erf x is based on the following rational Chebyshev expansion for erf x:
erf x≈x R ℓ,m x 2,
where R ℓ,m denotes a rational function of degree ℓ in the numerator and m in the denominator.
For x>x^ the value of erf x is based on a rational Chebyshev expansion for erfc x: for x^<x≤4 the value is based on the expansion
erfc x≈e x 2 R ℓ,m x;
and for x>4 it is based on the expansion
erfc x≈e x 2 x 1 π+1 x 2 R ℓ,m 1/x 2.
For each expansion, the specific values of ℓ and m are selected to be minimal such that the maximum relative error in the expansion is of the order 10-d, where d is the maximum number of decimal digits that can be accurately represented for the particular implementation (see X02BEF).
For x≥xhi there is a danger of setting underflow in erfc x (the value of xhi is given in the Users' Note for your implementation). For x≥xhi, S15AEF returns erf x=1; for x≤-xhi it returns erf x=-1.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Cody W J (1969) Rational Chebyshev approximations for the error function Math.Comp. 23 631–637

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

There are no failure exits from S15AEF. The argument IFAIL has been included for consistency with other routines in this chapter.

7 Accuracy

See Section 7 in S15ADF.

8 Parallelism and Performance

S15AEF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s15aefe.f90)

10.2 Program Data

Program Data (s15aefe.d)

10.3 Program Results

Program Results (s15aefe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S15AFF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S15AFF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S15AFF returns a value for Dawson's Integral, F x, via the function name.

2 Specification

FUNCTION S15AFF ( X, IFAIL)
REAL (KIND=nag_wp) S15AFF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S15AFF evaluates an approximation for Dawson's Integral
F x=e-x 2∫0 x e t 2 dt.
The routine is based on two Chebyshev expansions:
For 0<x≤4,
F x=x∑r=0′arTr t,   where  t=2 x 4 2-1.
For x>4,
F x=1 x∑r=0′brTr t,   where  t=2 4 x 2-1.
For x near zero, F x≃x, and for x large, F x≃ 1 2 x . These approximations are used for those values of x for which the result is correct to machine precision.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

There are no failure exits from this routine.

7 Accuracy

Let δ and ε be the relative errors in the argument and result respectively.
If δ is considerably greater than the machine precision (i.e., if δ is due to data errors etc.), then ε and δ are approximately related by:
ε≃ x 1-2 xF x F x δ.
The following graph shows the behaviour of the error amplification factor x 1-2 xF x F x :
Figure 1
However if δ is of the same order as machine precision, then rounding errors could make ε somewhat larger than the above relation indicates. In fact ε will be largely independent of x or δ, but will be of the order of a few times the machine precision.

8 Parallelism and Performance

S15AFF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s15affe.f90)

10.2 Program Data

Program Data (s15affe.d)

10.3 Program Results

Program Results (s15affe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S15AGF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S15AGF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S15AGF returns the value of the scaled complementary error function erfcx x, via the function name.

2 Specification

FUNCTION S15AGF ( X, IFAIL)
REAL (KIND=nag_wp) S15AGF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S15AGF calculates an approximate value for the scaled complementary error function
erfcx x = e x 2 erfc x = 2 π e x 2 ∫x∞ e-t 2 dt = e x 2 1- erf x .
Let x^ be the root of the equation erfc x-erf x=0 (then x^≈0.46875). For x≤x^ the value of erfcx x is based on the following rational Chebyshev expansion for erf x:
erf x≈x R ℓ,m x 2,
where R ℓ,m denotes a rational function of degree ℓ in the numerator and m in the denominator.
For x>x^ the value of erfcx x is based on a rational Chebyshev expansion for erfc x: for x^<x≤4 the value is based on the expansion
erfc x≈e x 2 R ℓ,m x;
and for x>4 it is based on the expansion
erfc x≈e x 2 x 1 π+1 x 2 R ℓ,m 1/x 2.
For each expansion, the specific values of ℓ and m are selected to be minimal such that the maximum relative error in the expansion is of the order 10-d, where d is the maximum number of decimal digits that can be accurately represented for the particular implementation (see X02BEF).
Asymptotically, erfcx x∼1/π x. There is a danger of setting underflow in erfcx x whenever x≥xhi=min xhuge,1/π xtiny, where xhuge is the largest positive model number (see X02ALF) and xtiny is the smallest positive model number (see X02AKF). In this case S15AGF exits with IFAIL=1 and returns erfcx x=0. For x in the range 1/2 ε≤x<xhi, where ε is the machine precision, the asymptotic value 1/π x is returned for erfcx x and S15AGF exits with IFAIL=2.
There is a danger of setting overflow in e x 2 whenever x<xneg=-log xhuge/2. In this case S15AGF exits with IFAIL=3 and returns erfcx x=xhuge.
The values of xhi, 1/2 ε and xneg are given in the Users' Note for your implementation.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Cody W J (1969) Rational Chebyshev approximations for the error function Math.Comp. 23 631–637

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if IFAIL≠0 on exit, the recommended value is -1. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Note: S15AGF may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the routine:
IFAIL=1
On entry, X=value and the constant xhi=value.
Constraint: X<xhi.
IFAIL=2
On entry, X was in the interval value,value where erfcx X is approximately 1/π*X: X=value.
IFAIL=3
On entry, X=value and the constant xneg=value.
Constraint: X≥xneg.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The relative error in computing erfcx x may be estimated by evaluating
E= erfcx x - e x 2 ∑ n=1 ∞ In erfc x erfcx x ,
where In denotes repeated integration. Empirical results suggest that on the interval x^,2 the loss in base b significant digits for maximum relative error is around 3.3, while for root-mean-square relative error on that interval it is 1.2 (see X02BHF for the definition of the model parameter b). On the interval 2,20 the values are around 3.5 for maximum and 0.45 for root-mean-square relative errors; note that on these two intervals erfc x is the primary computation. See also Section 7 in S15ADF.

8 Parallelism and Performance

S15AGF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s15agfe.f90)

10.2 Program Data

Program Data (s15agfe.d)

10.3 Program Results

Program Results (s15agfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S15DDF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S15DDF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S15DDF computes values of the function w z=e-z 2 erfc-iz, for complex z.

2 Specification

FUNCTION S15DDF ( Z, IFAIL)
COMPLEX (KIND=nag_wp) S15DDF
INTEGER | IFAIL
COMPLEX (KIND=nag_wp) | Z

3 Description

S15DDF computes values of the function w z=e-z 2 erfc-iz, where erfc⁡z is the complementary error function
erfc⁡z=2 π∫z∞e-t 2 dt,
for complex z. The method used is that in Gautschi (1970) for z in the first quadrant of the complex plane, and is extended for z in other quadrants via the relations w-z=2 e-z 2-w z and w z¯=w-z¯. Following advice in Gautschi (1970) and van der Laan and Temme (1984), the code in Gautschi (1969) has been adapted to work in various precisions up to 18 decimal places. The real part of w z is sometimes known as the Voigt function.

4 References

Gautschi W (1969) Algorithm 363: Complex error function Comm. ACM 12 635
Gautschi W (1970) Efficient computation of the complex error function SIAM J. Numer. Anal. 7 187–198
van der Laan C G and Temme N M (1984) Calculation of special functions: the gamma function, the exponential integrals and error-like functions CWI Tract 10 Centre for Mathematics and Computer Science, Amsterdam

5 Arguments

1:   Z – COMPLEX (KIND=nag_wp)Input
On entry: the argument z of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
The real part of the result overflows, and is set to the largest safe number with the correct sign. The imaginary part of the result is meaningful.
IFAIL=2
The imaginary part of the result overflows, and is set to the largest safe number with the correct sign. The real part of the result is meaningful.
IFAIL=3
Both real and imaginary parts of the result overflow, and are set to the largest safe number with the correct signs.
IFAIL=4
The result returned is accurate to less than half precision, due to the size of an intermediate result.
IFAIL=5
The result returned has no precision, due to the size of an intermediate result, and is set to zero.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The accuracy of the returned result depends on the argument z. If z lies in the first or second quadrant of the complex plane (i.e., Im z is greater than or equal to zero), the result should be accurate almost to machine precision, except that there is a limit of about 18 decimal places on the achievable accuracy because constants in the routine are given to this precision. With such arguments, IFAIL can only return as IFAIL=0.
If however Im z is less than zero, accuracy may be lost in two ways; firstly, in the evaluation of e-z 2, if Im-z 2 is large, in which case a warning will be issued through IFAIL=4 or 5; and secondly, near the zeros of the required function, where precision is lost due to cancellation, in which case no warning is given – the result has absolute accuracy rather than relative accuracy. Note also that in this half-plane, one or both parts of the result may overflow – this is signalled through IFAIL=1, 2 or 3.

8 Parallelism and Performance

S15DDF is not threaded in any implementation.

9 Further Comments

The time taken for a call of S15DDF depends on the argument z, the time increasing as z→0.0.
S15DDF may be used to compute values of erfc⁡z and erf⁡z for complex z by the relations erfc⁡z=e-z 2 w iz, erf⁡z=1-erfc⁡z. (For real arguments, S15ADF and S15AEF should be used.)

10 Example

This example reads values of the argument z from a file, evaluates the function at each value of z and prints the results.

10.1 Program Text

Program Text (s15ddfe.f90)

10.2 Program Data

Program Data (s15ddfe.d)

10.3 Program Results

Program Results (s15ddfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S17ACF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S17ACF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S17ACF returns the value of the Bessel function Y 0 x, via the function name.

2 Specification

FUNCTION S17ACF ( X, IFAIL)
REAL (KIND=nag_wp) S17ACF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S17ACF evaluates an approximation to the Bessel function of the second kind Y 0 x.
Note: Y 0 x is undefined for x≤0 and the routine will fail for such arguments.
The routine is based on four Chebyshev expansions:
For 0<x≤8,
Y 0 x=2 π ln⁡x∑r=0′arTr t+∑r=0′brTr t,   with ​t=2 x 8 2-1.
For x>8,
Y 0 x=2 πx P 0 x sin x-π 4+Q 0 x cos x-π 4
where P 0 x=∑′r=0 crTr t,
and Q 0 x= 8 x∑′r=0 drTr t,with ​ t=2 8 x 2-1.
For x near zero, Y 0 x≃2 π ln x 2+γ , where γ denotes Euler's constant. This approximation is used when x is sufficiently small for the result to be correct to machine precision.
For very large x, it becomes impossible to provide results with any reasonable accuracy (see Section 7), hence the routine fails. Such arguments contain insufficient information to determine the phase of oscillation of Y 0 x; only the amplitude, 2 πn , can be determined and this is returned on soft failure. The range for which this occurs is roughly related to machine precision; the routine will fail if x≳1/machine precision (see the Users' Note for your implementation for details).

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Clenshaw C W (1962) Chebyshev Series for Mathematical Functions Mathematical tables HMSO

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
Constraint: X>0.0.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
X is too large. On soft failure the routine returns the amplitude of the Y 0 oscillation, 2/πx.
IFAIL=2
X≤0.0, Y 0 is undefined. On soft failure the routine returns zero.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Let δ be the relative error in the argument and E be the absolute error in the result. (Since Y 0 x oscillates about zero, absolute error and not relative error is significant, except for very small x.)
If δ is somewhat larger than the machine representation error (e.g., if δ is due to data errors etc.), then E and δ are approximately related by
E≃x Y 1 x δ
(provided E is also within machine bounds). Figure 1 displays the behaviour of the amplification factor x Y 1 x.
However, if δ is of the same order as the machine representation errors, then rounding errors could make E slightly larger than the above relation predicts.
For very small x, the errors are essentially independent of δ and the routine should provide relative accuracy bounded by the machine precision.
For very large x, the above relation ceases to apply. In this region, Y 0 x≃ 2 πx sin x- π 4. The amplitude 2 πx can be calculated with reasonable accuracy for all x, but sin x-π 4 cannot. If x- π 4 is written as 2 Nπ+θ where N is an integer and 0≤θ<2 π, then sin x- π 4 is determined by θ only. If x≳δ-1, θ cannot be determined with any accuracy at all. Thus if x is greater than, or of the order of the inverse of machine precision, it is impossible to calculate the phase of Y 0 x and the routine must fail.
Figure 1

8 Parallelism and Performance

S17ACF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s17acfe.f90)

10.2 Program Data

Program Data (s17acfe.d)

10.3 Program Results

Program Results (s17acfe.r)

GnuplotProduced by GNUPLOT 4.6 patchlevel 3 −0.6 −0.4 −0.2 0 0.2 0.4 0.6 0 5 10 15 20 25 30 35 40 45 50 Y0(x) x Example Program Returned Values for the Bessel Function Y0(x) gnuplot_plot_1
S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S17ADF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S17ADF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S17ADF returns the value of the Bessel function Y 1 x, via the function name.

2 Specification

FUNCTION S17ADF ( X, IFAIL)
REAL (KIND=nag_wp) S17ADF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S17ADF evaluates an approximation to the Bessel function of the second kind Y 1 x.
Note: Y 1 x is undefined for x≤0 and the routine will fail for such arguments.
The routine is based on four Chebyshev expansions:
For 0<x≤8,
Y 1 x=2 π ln⁡x x 8∑′r=0 arTr t-2 πx +x 8∑′r=0 brTr t,   with ​t=2 x 8 2-1.
For x>8,
Y 1 x=2 πx P 1 x sin x-3 π 4+Q 1 x cos x-3 π 4
where P 1 x=∑′r=0 crTr t,
and Q 1 x= 8 x∑′r=0 drTr t, with t=2 8 x 2-1.
For x near zero, Y 1 x≃- 2 πx . This approximation is used when x is sufficiently small for the result to be correct to machine precision. For extremely small x, there is a danger of overflow in calculating - 2 πx and for such arguments the routine will fail.
For very large x, it becomes impossible to provide results with any reasonable accuracy (see Section 7), hence the routine fails. Such arguments contain insufficient information to determine the phase of oscillation of Y 1 x; only the amplitude, 2 πx , can be determined and this is returned on soft failure. The range for which this occurs is roughly related to machine precision; the routine will fail if x≳1/machine precision (see the Users' Note for your implementation for details).

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Clenshaw C W (1962) Chebyshev Series for Mathematical Functions Mathematical tables HMSO

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
Constraint: X>0.0.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
X is too large. On soft failure the routine returns the amplitude of the Y 1 oscillation, 2 πx .
IFAIL=2
X≤0.0, Y 1 is undefined. On soft failure the routine returns zero.
IFAIL=3
X is too close to zero, there is a danger of overflow. On soft failure, the routine returns the value of Y 1 x at the smallest valid argument.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Let δ be the relative error in the argument and E be the absolute error in the result. (Since Y 1 x oscillates about zero, absolute error and not relative error is significant, except for very small x.)
If δ is somewhat larger than the machine precision (e.g., if δ is due to data errors etc.), then E and δ are approximately related by:
E ≃ x Y 0 x - Y 1 x δ
(provided E is also within machine bounds). Figure 1 displays the behaviour of the amplification factor x Y 0 x-Y 1 x.
However, if δ is of the same order as machine precision, then rounding errors could make E slightly larger than the above relation predicts.
For very small x, absolute error becomes large, but the relative error in the result is of the same order as δ.
For very large x, the above relation ceases to apply. In this region, Y 1 x ≃ 2 πx sin x- 3 π 4 . The amplitude 2 πx can be calculated with reasonable accuracy for all x, but sin x- 3 π 4 cannot. If x- 3 π 4 is written as 2 Nπ+θ where N is an integer and 0≤θ<2 π, then sin x- 3 π 4 is determined by θ only. If x>δ-1, θ cannot be determined with any accuracy at all. Thus if x is greater than, or of the order of, the inverse of the machine precision, it is impossible to calculate the phase of Y 1 x and the routine must fail.
Figure 1

8 Parallelism and Performance

S17ADF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s17adfe.f90)

10.2 Program Data

Program Data (s17adfe.d)

10.3 Program Results

Program Results (s17adfe.r)

GnuplotProduced by GNUPLOT 4.6 patchlevel 3 −2 −1.5 −1 −0.5 0 0.5 0 5 10 15 20 25 30 35 40 45 50 Y1(x) x Example Program Returned Values for the Bessel Function Y1(x) gnuplot_plot_1
S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S17AEF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S17AEF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S17AEF returns the value of the Bessel function J 0 x, via the function name.

2 Specification

FUNCTION S17AEF ( X, IFAIL)
REAL (KIND=nag_wp) S17AEF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S17AEF evaluates an approximation to the Bessel function of the first kind J 0 x.
Note: J 0-x=J 0 x, so the approximation need only consider x≥0.
The routine is based on three Chebyshev expansions:
For 0<x≤8,
J 0 x=∑′r=0 arTr t,   with ​t=2 x 8 2 -1.
For x>8,
J 0 x= 2 πx P 0 x cos x-π 4-Q 0 x sin x- π 4 ,
where P 0 x=∑′r=0 brTr t,
and Q 0 x= 8 x∑′r=0 crTr t,
with t=2 8 x 2-1.
For x near zero, J 0 x≃1. This approximation is used when x is sufficiently small for the result to be correct to machine precision.
For very large x, it becomes impossible to provide results with any reasonable accuracy (see Section 7), hence the routine fails. Such arguments contain insufficient information to determine the phase of oscillation of J 0 x; only the amplitude, 2 π x , can be determined and this is returned on soft failure. The range for which this occurs is roughly related to machine precision; the routine will fail if x≳1/machine precision (see the Users' Note for your implementation for details).

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Clenshaw C W (1962) Chebyshev Series for Mathematical Functions Mathematical tables HMSO

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
X is too large. On soft failure the routine returns the amplitude of the J 0 oscillation, 2 π x .
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Let δ be the relative error in the argument and E be the absolute error in the result. (Since J 0 x oscillates about zero, absolute error and not relative error is significant.)
If δ is somewhat larger than the machine precision (e.g., if δ is due to data errors etc.), then E and δ are approximately related by:
E≃x J 1 x δ
(provided E is also within machine bounds). Figure 1 displays the behaviour of the amplification factor x J 1 x.
However, if δ is of the same order as machine precision, then rounding errors could make E slightly larger than the above relation predicts.
For very large x, the above relation ceases to apply. In this region, J 0 x≃ 2 π x cos x- π 4. The amplitude 2 π x can be calculated with reasonable accuracy for all x, but cos x- π 4 cannot. If x- π 4 is written as 2 Nπ+θ where N is an integer and 0≤θ<2 π, then cos x- π 4 is determined by θ only. If x≳δ-1, θ cannot be determined with any accuracy at all. Thus if x is greater than, or of the order of, the inverse of the machine precision, it is impossible to calculate the phase of J 0 x and the routine must fail.
Figure 1

8 Parallelism and Performance

S17AEF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s17aefe.f90)

10.2 Program Data

Program Data (s17aefe.d)

10.3 Program Results

Program Results (s17aefe.r)

GnuplotProduced by GNUPLOT 4.6 patchlevel 3 −0.4 −0.2 0 0.2 0.4 0.6 0.8 1 −20 −10 0 10 20 J0(x) x Example Program Returned Values for the Bessel Function J0(x) gnuplot_plot_1
S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S17AFF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S17AFF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S17AFF returns the value of the Bessel function J 1 x, via the function name.

2 Specification

FUNCTION S17AFF ( X, IFAIL)
REAL (KIND=nag_wp) S17AFF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S17AFF evaluates an approximation to the Bessel function of the first kind J 1 x.
Note: J 1-x=-J 1 x, so the approximation need only consider x≥0.
The routine is based on three Chebyshev expansions:
For 0<x≤8,
J 1 x=x 8∑′r=0 arTr t,   with ​t=2 x 8 2-1.
For x>8,
J 1 x=2 πx P 1 x cos x-3 π 4-Q 1 x sin x-3 π 4
where P 1 x=∑′r=0 brTr t,
and Q 1 x= 8 x∑′r=0 crTr t,
with t=2 8 x 2-1.
For x near zero, J 1 x≃ x 2 . This approximation is used when x is sufficiently small for the result to be correct to machine precision.
For very large x, it becomes impossible to provide results with any reasonable accuracy (see Section 7), hence the routine fails. Such arguments contain insufficient information to determine the phase of oscillation of J 1 x; only the amplitude, 2 π x , can be determined and this is returned on soft failure. The range for which this occurs is roughly related to machine precision; the routine will fail if x≳1/machine precision (see the Users' Note for your implementation for details).

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Clenshaw C W (1962) Chebyshev Series for Mathematical Functions Mathematical tables HMSO

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
X is too large. On soft failure the routine returns the amplitude of the J 1 oscillation, 2 π x .
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Let δ be the relative error in the argument and E be the absolute error in the result. (Since J 1 x oscillates about zero, absolute error and not relative error is significant.)
If δ is somewhat larger than machine precision (e.g., if δ is due to data errors etc.), then E and δ are approximately related by:
E≃x J 0 x-J 1 x δ
(provided E is also within machine bounds). Figure 1 displays the behaviour of the amplification factor x J 0 x-J 1 x.
However, if δ is of the same order as machine precision, then rounding errors could make E slightly larger than the above relation predicts.
For very large x, the above relation ceases to apply. In this region, J 1 x≃ 2 π x cos x- 3 π 4. The amplitude 2 π x can be calculated with reasonable accuracy for all x, but cos x- 3 π 4 cannot. If x- 3 π 4 is written as 2 Nπ+θ where N is an integer and 0≤θ<2 π, then cos x- 3 π 4 is determined by θ only. If x≳δ-1, θ cannot be determined with any accuracy at all. Thus if x is greater than, or of the order of, the reciprocal of machine precision, it is impossible to calculate the phase of J 1 x and the routine must fail.
Figure 1

8 Parallelism and Performance

S17AFF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s17affe.f90)

10.2 Program Data

Program Data (s17affe.d)

10.3 Program Results

Program Results (s17affe.r)

GnuplotProduced by GNUPLOT 4.6 patchlevel 3 −0.6 −0.4 −0.2 0 0.2 0.4 0.6 −20 −10 0 10 20 J1(x) x Example Program Returned Values for the Bessel Function J1(x) gnuplot_plot_1
S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S17AGF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S17AGF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S17AGF returns a value for the Airy function, Ai x, via the function name.

2 Specification

FUNCTION S17AGF ( X, IFAIL)
REAL (KIND=nag_wp) S17AGF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S17AGF evaluates an approximation to the Airy function, Ai x. It is based on a number of Chebyshev expansions:
For x<-5,
Ai x=a t sin⁡z-b t cos⁡z-x 1/4
where z= π 4+ 23-x 3, and a t and b t are expansions in the variable t=-2 5 x 3-1.
For -5≤x≤0,
Ai x=f t-xg t,
where f and g are expansions in t=-2 x 5 3-1.
For 0<x<4.5,
Ai x=e-3 x/2 y t,
where y is an expansion in t=4 x/9-1.
For 4.5≤x<9,
Ai x=e-5 x/2 u t,
where u is an expansion in t=4 x/9-3.
For x≥9,
Ai x=e-z v t x 1/4,
where z= 23 x 3 and v is an expansion in t=2 18 z-1.
For x<machine precision, the result is set directly to Ai 0. This both saves time and guards against underflow in intermediate calculations.
For large negative arguments, it becomes impossible to calculate the phase of the oscillatory function with any precision and so the routine must fail. This occurs if x<- 3 2 ε 2/3 , where ε is the machine precision.
For large positive arguments, where Ai decays in an essentially exponential manner, there is a danger of underflow so the routine must fail.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
X is too large and positive. On soft failure, the routine returns zero. See also the Users' Note for your implementation.
IFAIL=2
X is too large and negative. On soft failure, the routine returns zero. See also the Users' Note for your implementation.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

For negative arguments the function is oscillatory and hence absolute error is the appropriate measure. In the positive region the function is essentially exponential-like and here relative error is appropriate. The absolute error, E, and the relative error, ε, are related in principle to the relative error in the argument, δ, by
E≃ x Ai′x δ, ε≃ x Ai′x Ai x δ.
In practice, approximate equality is the best that can be expected. When δ, ε or E is of the order of the machine precision, the errors in the result will be somewhat larger.
For small x, errors are strongly damped by the function and hence will be bounded by the machine precision.
For moderate negative x, the error behaviour is oscillatory but the amplitude of the error grows like
amplitude Eδ ∼x 5/4 π.
However the phase error will be growing roughly like 23 x 3 and hence all accuracy will be lost for large negative arguments due to the impossibility of calculating sin and cos to any accuracy if 23 x 3> 1 δ .
For large positive arguments, the relative error amplification is considerable:
ε δ ∼x 3.
This means a loss of roughly two decimal places accuracy for arguments in the region of 20. However very large arguments are not possible due to the danger of setting underflow and so the errors are limited in practice.

8 Parallelism and Performance

S17AGF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s17agfe.f90)

10.2 Program Data

Program Data (s17agfe.d)

10.3 Program Results

Program Results (s17agfe.r)

GnuplotProduced by GNUPLOT 4.6 patchlevel 3 −0.4 −0.2 0 0.2 0.4 0.6 −25 −20 −15 −10 −5 0 5 10 Ai(x) x Example Program Returns a Value for the Airy Function Ai(x) gnuplot_plot_1
S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S17AHF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S17AHF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S17AHF returns a value of the Airy function, Bi x, via the function name.

2 Specification

FUNCTION S17AHF ( X, IFAIL)
REAL (KIND=nag_wp) S17AHF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S17AHF evaluates an approximation to the Airy function Bi x. It is based on a number of Chebyshev expansions.
For x<-5,
Bi x=a t cos⁡z+b t sin⁡z-x 1/4,
where z= π 4+ 23-x 3 and a t and b t are expansions in the variable t=-2 5 x 3-1.
For -5≤x≤0,
Bi x=3 f t+xg t,
where f and g are expansions in t=-2 x 5 3-1.
For 0<x<4.5,
Bi x=e 11 x/8 y t,
where y is an expansion in t=4 x/9-1.
For 4.5≤x<9,
Bi x=e 5 x/2 v t,
where v is an expansion in t=4 x/9-3.
For x≥9,
Bi x=ez u t x 1/4,
where z= 23 x 3 and u is an expansion in t=2 18 z-1.
For x<machine precision, the result is set directly to Bi 0. This both saves time and avoids possible intermediate underflows.
For large negative arguments, it becomes impossible to calculate the phase of the oscillating function with any accuracy so the routine must fail. This occurs if x<- 3 2 ε 2/3, where ε is the machine precision.
For large positive arguments, there is a danger of causing overflow since Bi grows in an essentially exponential manner, so the routine must fail.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
X is too large and positive. On soft failure, the routine returns zero. (see the Users' Note for your implementation for details)
IFAIL=2
X is too large and negative. On soft failure, the routine returns zero. See also the Users' Note for your implementation.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

For negative arguments the function is oscillatory and hence absolute error is the appropriate measure. In the positive region the function is essentially exponential-like and here relative error is appropriate. The absolute error, E, and the relative error, ε, are related in principle to the relative error in the argument, δ, by
E≃ x Bi′x δ,ε≃ x Bi′x Bi x δ.
In practice, approximate equality is the best that can be expected. When δ, ε or E is of the order of the machine precision, the errors in the result will be somewhat larger.
For small x, errors are strongly damped and hence will be bounded essentially by the machine precision.
For moderate to large negative x, the error behaviour is clearly oscillatory but the amplitude of the error grows like amplitude Eδ ∼ x 5/4 π .
However the phase error will be growing roughly as 23 x 3 and hence all accuracy will be lost for large negative arguments. This is due to the impossibility of calculating sin and cos to any accuracy if 23 x 3> 1 δ .
For large positive arguments, the relative error amplification is considerable:
εδ∼x 3.
This means a loss of roughly two decimal places accuracy for arguments in the region of 20. However very large arguments are not possible due to the danger of causing overflow and errors are therefore limited in practice.

8 Parallelism and Performance

S17AHF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s17ahfe.f90)

10.2 Program Data

Program Data (s17ahfe.d)

10.3 Program Results

Program Results (s17ahfe.r)

GnuplotProduced by GNUPLOT 4.6 patchlevel 3 0 5 10 15 −10 −8 −6 −4 −2 0 2 4 Bi(x) x Example Program Returns a Value of the Airy Function Bi(x) gnuplot_plot_1
S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S17AJF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S17AJF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S17AJF returns a value of the derivative of the Airy function Ai x, via the function name.

2 Specification

FUNCTION S17AJF ( X, IFAIL)
REAL (KIND=nag_wp) S17AJF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S17AJF evaluates an approximation to the derivative of the Airy function Ai x. It is based on a number of Chebyshev expansions.
For x<-5,
Ai′x=-x 4 a t cos⁡z+b t ζ sin⁡z ,
where z= π 4+ζ, ζ= 23-x 3 and a t and b t are expansions in variable t=-2 5 x 3-1.
For -5≤x≤0,
Ai′x=x 2 f t-g t,
where f and g are expansions in t=-2 x 5 3-1.
For 0<x<4.5,
Ai′x=e-11 x/8 y t,
where y t is an expansion in t=4 x 9-1.
For 4.5≤x<9,
Ai′x=e-5 x/2 v t,
where v t is an expansion in t=4 x 9-3.
For x≥9,
Ai′x = x 4 e-z u t ,
where z= 23 x 3 and u t is an expansion in t=2 18 z-1.
For x< the square of the machine precision, the result is set directly to Ai′0. This both saves time and avoids possible intermediate underflows.
For large negative arguments, it becomes impossible to calculate a result for the oscillating function with any accuracy and so the routine must fail. This occurs for x<- π ε 4/7 , where ε is the machine precision.
For large positive arguments, where Ai′ decays in an essentially exponential manner, there is a danger of underflow so the routine must fail.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
X is too large and positive. On soft failure, the routine returns zero. (see the Users' Note for your implementation for details)
IFAIL=2
X is too large and negative. On soft failure, the routine returns zero. See also the Users' Note for your implementation.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

For negative arguments the function is oscillatory and hence absolute error is the appropriate measure. In the positive region the function is essentially exponential in character and here relative error is needed. The absolute error, E, and the relative error, ε, are related in principle to the relative error in the argument, δ, by
E≃ x 2 Ai x δ ε≃ x 2 Ai x Ai′x δ.
In practice, approximate equality is the best that can be expected. When δ, ε or E is of the order of the machine precision, the errors in the result will be somewhat larger.
For small x, positive or negative, errors are strongly attenuated by the function and hence will be roughly bounded by the machine precision.
For moderate to large negative x, the error, like the function, is oscillatory; however the amplitude of the error grows like
x 7/4 π.
Therefore it becomes impossible to calculate the function with any accuracy if x 7/4> π δ .
For large positive x, the relative error amplification is considerable:
εδ≃x 3.
However, very large arguments are not possible due to the danger of underflow. Thus in practice error amplification is limited.

8 Parallelism and Performance

S17AJF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s17ajfe.f90)

10.2 Program Data

Program Data (s17ajfe.d)

10.3 Program Results

Program Results (s17ajfe.r)

GnuplotProduced by GNUPLOT 4.6 patchlevel 3 −1.5 −1 −0.5 0 0.5 1 1.5 −15 −10 −5 0 5 Ai(x) x Example Program Returns a Value for the Derivative of the Airy Function Ai(x) gnuplot_plot_1
S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S17AKF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S17AKF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S17AKF returns a value for the derivative of the Airy function Bi x, via the function name.

2 Specification

FUNCTION S17AKF ( X, IFAIL)
REAL (KIND=nag_wp) S17AKF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S17AKF calculates an approximate value for the derivative of the Airy function Bi x. It is based on a number of Chebyshev expansions.
For x<-5,
Bi′x=-x 4 -a t sin⁡z+b t ζ cos⁡z ,
where z= π 4+ζ, ζ= 23-x 3 and a t and b t are expansions in the variable t=-2 5 x 3-1.
For -5≤x≤0,
Bi′x=3 x 2 f t+g t,
where f and g are expansions in t=-2 x 5 3-1.
For 0<x<4.5,
Bi′x=e 3 x/2 y t,
where y t is an expansion in t=4 x/9-1.
For 4.5≤x<9,
Bi′x=e 21 x/8 u t,
where u t is an expansion in t=4 x/9-3.
For x≥9,
Bi′x=x 4 ez v t,
where z= 23 x 3 and v t is an expansion in t=2 18 z-1.
For x< the square of the machine precision, the result is set directly to Bi′0. This saves time and avoids possible underflows in calculation.
For large negative arguments, it becomes impossible to calculate a result for the oscillating function with any accuracy so the routine must fail. This occurs for x<- π ε 4/7 , where ε is the machine precision.
For large positive arguments, where Bi′ grows in an essentially exponential manner, there is a danger of overflow so the routine must fail.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
X is too large and positive. On soft failure, the routine returns zero. (see the Users' Note for your implementation for details)
IFAIL=2
X is too large and negative. On soft failure the routine returns zero. (see the Users' Note for your implementation for details)
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

For negative arguments the function is oscillatory and hence absolute error is appropriate. In the positive region the function has essentially exponential behaviour and hence relative error is needed. The absolute error, E, and the relative error ε, are related in principle to the relative error in the argument δ, by
E≃ x 2 Bi x δ  ε≃ x 2 Bi x Bi′x δ.
In practice, approximate equality is the best that can be expected. When δ, ε or E is of the order of the machine precision, the errors in the result will be somewhat larger.
For small x, positive or negative, errors are strongly attenuated by the function and hence will effectively be bounded by the machine precision.
For moderate to large negative x, the error is, like the function, oscillatory. However, the amplitude of the absolute error grows like x 7/4 π . Therefore it becomes impossible to calculate the function with any accuracy if x 7/4> π δ .
For large positive x, the relative error amplification is considerable: εδ∼x 3. However, very large arguments are not possible due to the danger of overflow. Thus in practice the actual amplification that occurs is limited.

8 Parallelism and Performance

S17AKF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s17akfe.f90)

10.2 Program Data

Program Data (s17akfe.d)

10.3 Program Results

Program Results (s17akfe.r)

GnuplotProduced by GNUPLOT 4.6 patchlevel 3 −2 0 2 4 6 8 10 −10 −8 −6 −4 −2 0 2 4 Bi(x) x Example Program Returns a Value for the Derivative of the Airy Function Bi(x) gnuplot_plot_1
S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S17ALF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S17ALF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S17ALF determines the leading N zeros of one of the Bessel functions Jα x, Yα x, Jα′x or Yα′x for real x and non-negative α.

2 Specification

SUBROUTINE S17ALF ( A, N, MODE, REL, X, IFAIL)
INTEGER | N, MODE, IFAIL
REAL (KIND=nag_wp) | A, REL, X(N)

3 Description

S17ALF attempts to find the leading N zeros of one of the Bessel functions Jα x, Yα x, Jα′x or Yα′x, where x is real. When α is real, these functions each have an infinite number of real zeros, all of which are simple with the possible exception of x=0. If α≥0, the nth positive zero is denoted by j α,n,j α,n′,y α,n and y α,n′, respectively, for n=1,2,…,N, except that x=0 is counted as the first zero of Jα′x when α=0. Since J 0′x=-J 1 x, it therefore follows that j 0,1′=0 and j 0,n′=-j 1,n-1 for n=2,3,…,N-1. Further details can be found in Section 9.5 of Abramowitz and Stegun (1972).
S17ALF is based on Algol 60 procedures given by Temme (1979). Initial approximations to the zeros are computed from asymptotic expansions. These are then improved by higher-order Newton iteration making use of the differential equation for the Bessel functions.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Temme N M (1976) On the numerical evaluation of the ordinary Bessel function of the second kind J. Comput. Phys. 21 343–350
Temme N M (1979) An algorithm with Algol 60 program for the computation of the zeros of ordinary Bessel functions and those of their derivatives J. Comput. Phys. 32 270–279

5 Arguments

1:   A – REAL (KIND=nag_wp)Input
On entry: the order α of the function.
Constraint: 0.0≤A≤100000.0.
2:   N – INTEGERInput
On entry: the number N of zeros required.
Constraint: N≥1.
3:   MODE – INTEGERInput
On entry: specifies the form of the function whose zeros are required.
MODE=1
The zeros of Jα x are required.
MODE=2
The zeros of Yα x are required;
MODE=3
The zeros of Jα′x are required;
MODE=4
The zeros of Yα′x are required.
Constraint: 1≤MODE≤4.
4:   REL – REAL (KIND=nag_wp)Input
On entry: the relative accuracy to which the zeros are required.
Suggested value: the square root of the machine precision.
Constraint: REL>0.0.
5:   X N – REAL (KIND=nag_wp) arrayOutput
On exit: the N required zeros of the function specified by MODE.
6:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | A<0.0,
or | A>100000.0,
or | N≤0,
or | MODE<1,
or | MODE>4,
or | REL≤0.0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

If the value of REL is set to 10-d, then the required zeros should have approximately d correct significant digits.

8 Parallelism and Performance

S17ALF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example determines the leading five positive zeros of the Bessel function J 0 x.

10.1 Program Text

Program Text (s17alfe.f90)

10.2 Program Data

Program Data (s17alfe.d)

10.3 Program Results

Program Results (s17alfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S17AQF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S17AQF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S17AQF returns an array of values of the Bessel function Y 0 x.

2 Specification

SUBROUTINE S17AQF ( N, X, F, IVALID, IFAIL)
INTEGER | N, IVALID(N), IFAIL
REAL (KIND=nag_wp) | X(N), F(N)

3 Description

S17AQF evaluates an approximation to the Bessel function of the second kind Y 0 xi for an array of arguments xi, for i=1,2,…,n.
Note: Y 0 x is undefined for x≤0 and the routine will fail for such arguments.
The routine is based on four Chebyshev expansions:
For 0<x≤8,
Y 0 x = 2 π ln⁡x ∑′r=0 ar Tr t + ∑′r=0 br Tr t ,   with ​ t = 2 x 8 2 - 1 .
For x>8,
Y 0 x = 2 πx P 0 x sin x-π 4 + Q 0 x cos x-π 4
where P 0 x=∑′r=0 crTr t,
and Q 0 x= 8 x∑′r=0 drTr t,with ​ t=2 8 x 2-1.
For x near zero, Y 0 x≃2 π ln x 2+γ , where γ denotes Euler's constant. This approximation is used when x is sufficiently small for the result to be correct to machine precision.
For very large x, it becomes impossible to provide results with any reasonable accuracy (see Section 7), hence the routine fails. Such arguments contain insufficient information to determine the phase of oscillation of Y 0 x; only the amplitude, 2 πn , can be determined and this is returned on soft failure. The range for which this occurs is roughly related to machine precision; the routine will fail if x≳1/machine precision (see the Users' Note for your implementation for details).

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Clenshaw C W (1962) Chebyshev Series for Mathematical Functions Mathematical tables HMSO

5 Arguments

1:   N – INTEGERInput
On entry: n, the number of points.
Constraint: N≥0.
2:   X N – REAL (KIND=nag_wp) arrayInput
On entry: the argument xi of the function, for i=1,2,…,N.
Constraint: X i>0.0, for i=1,2,…,N.
3:   F N – REAL (KIND=nag_wp) arrayOutput
On exit: Y 0 xi, the function values.
4:   IVALID N – INTEGER arrayOutput
On exit: IVALID i contains the error code for xi, for i=1,2,…,N.
IVALID i=0
No error.
IVALID i=1
On entry, xi is too large. F i contains the amplitude of the Y 0 oscillation, 2 π xi .
IVALID i=2
On entry, xi≤0.0, Y 0 is undefined. F i contains 0.0.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, at least one value of X was invalid.
Check IVALID for more information.
IFAIL=2
On entry, N=value.
Constraint: N≥0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Let δ be the relative error in the argument and E be the absolute error in the result. (Since Y 0 x oscillates about zero, absolute error and not relative error is significant, except for very small x.)
If δ is somewhat larger than the machine representation error (e.g., if δ is due to data errors etc.), then E and δ are approximately related by
E ≃ x Y 1 x δ
(provided E is also within machine bounds). Figure 1 displays the behaviour of the amplification factor x Y 1 x.
However, if δ is of the same order as the machine representation errors, then rounding errors could make E slightly larger than the above relation predicts.
For very small x, the errors are essentially independent of δ and the routine should provide relative accuracy bounded by the machine precision.
For very large x, the above relation ceases to apply. In this region, Y 0 x≃ 2 πx sin x- π 4. The amplitude 2 πx can be calculated with reasonable accuracy for all x, but sin x-π 4 cannot. If x- π 4 is written as 2 Nπ+θ where N is an integer and 0≤θ<2 π, then sin x- π 4 is determined by θ only. If x≳δ-1, θ cannot be determined with any accuracy at all. Thus if x is greater than, or of the order of the inverse of machine precision, it is impossible to calculate the phase of Y 0 x and the routine must fail.
Figure 1

8 Parallelism and Performance

S17AQF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of X from a file, evaluates the function at each value of xi and prints the results.

10.1 Program Text

Program Text (s17aqfe.f90)

10.2 Program Data

Program Data (s17aqfe.d)

10.3 Program Results

Program Results (s17aqfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S17ARF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S17ARF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S17ARF returns an array of values of the Bessel function Y 1 x.

2 Specification

SUBROUTINE S17ARF ( N, X, F, IVALID, IFAIL)
INTEGER | N, IVALID(N), IFAIL
REAL (KIND=nag_wp) | X(N), F(N)

3 Description

S17ARF evaluates an approximation to the Bessel function of the second kind Y 1 xi for an array of arguments xi, for i=1,2,…,n.
Note: Y 1 x is undefined for x≤0 and the routine will fail for such arguments.
The routine is based on four Chebyshev expansions:
For 0<x≤8,
Y 1 x = 2 π ln⁡x x 8 ∑′r=0 ar Tr t - 2 πx + x 8 ∑′r=0 br Tr t ,   with ​ t = 2 x 8 2 - 1 .
For x>8,
Y 1 x = 2 πx P 1 x sin x - 3 π 4 + Q 1 x cos x - 3 π 4
where P 1 x = ∑′r=0 cr Tr t ,
and Q 1 x = 8 x ∑′r=0 dr Tr t , with t = 2 8 x 2 - 1 .
For x near zero, Y 1 x ≃ - 2 πx . This approximation is used when x is sufficiently small for the result to be correct to machine precision. For extremely small x, there is a danger of overflow in calculating - 2 πx and for such arguments the routine will fail.
For very large x, it becomes impossible to provide results with any reasonable accuracy (see Section 7), hence the routine fails. Such arguments contain insufficient information to determine the phase of oscillation of Y 1 x; only the amplitude, 2 πx , can be determined and this is returned on soft failure. The range for which this occurs is roughly related to machine precision; the routine will fail if x≳1/machine precision (see the Users' Note for your implementation for details).

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Clenshaw C W (1962) Chebyshev Series for Mathematical Functions Mathematical tables HMSO

5 Arguments

1:   N – INTEGERInput
On entry: n, the number of points.
Constraint: N≥0.
2:   X N – REAL (KIND=nag_wp) arrayInput
On entry: the argument xi of the function, for i=1,2,…,N.
Constraint: X i>0.0, for i=1,2,…,N.
3:   F N – REAL (KIND=nag_wp) arrayOutput
On exit: Y 1 xi, the function values.
4:   IVALID N – INTEGER arrayOutput
On exit: IVALID i contains the error code for xi, for i=1,2,…,N.
IVALID i=0
No error.
IVALID i=1
On entry, xi is too large. F i contains the amplitude of the Y 1 oscillation, 2 π xi .
IVALID i=2
On entry, xi≤0.0, Y 1 is undefined. F i contains 0.0.
IVALID i=3
xi is too close to zero, there is a danger of overflow. On soft failure, F i contains the value of Y 1 x at the smallest valid argument.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, at least one value of X was invalid.
Check IVALID for more information.
IFAIL=2
On entry, N=value.
Constraint: N≥0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Let δ be the relative error in the argument and E be the absolute error in the result. (Since Y 1 x oscillates about zero, absolute error and not relative error is significant, except for very small x.)
If δ is somewhat larger than the machine precision (e.g., if δ is due to data errors etc.), then E and δ are approximately related by:
E ≃ x Y 0 x - Y 1 x δ
(provided E is also within machine bounds). Figure 1 displays the behaviour of the amplification factor x Y 0 x-Y 1 x.
However, if δ is of the same order as machine precision, then rounding errors could make E slightly larger than the above relation predicts.
For very small x, absolute error becomes large, but the relative error in the result is of the same order as δ.
For very large x, the above relation ceases to apply. In this region, Y 1 x ≃ 2 πx sin x - 3 π 4 . The amplitude 2 πx can be calculated with reasonable accuracy for all x, but sin x- 3 π 4 cannot. If x- 3 π 4 is written as 2 Nπ+θ where N is an integer and 0≤θ<2 π, then sin x- 3 π 4 is determined by θ only. If x>δ-1, θ cannot be determined with any accuracy at all. Thus if x is greater than, or of the order of, the inverse of the machine precision, it is impossible to calculate the phase of Y 1 x and the routine must fail.
Figure 1

8 Parallelism and Performance

S17ARF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of X from a file, evaluates the function at each value of xi and prints the results.

10.1 Program Text

Program Text (s17arfe.f90)

10.2 Program Data

Program Data (s17arfe.d)

10.3 Program Results

Program Results (s17arfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S17ASF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S17ASF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S17ASF returns an array of values of the Bessel function J 0 x.

2 Specification

SUBROUTINE S17ASF ( N, X, F, IVALID, IFAIL)
INTEGER | N, IVALID(N), IFAIL
REAL (KIND=nag_wp) | X(N), F(N)

3 Description

S17ASF evaluates an approximation to the Bessel function of the first kind J 0 xi for an array of arguments xi, for i=1,2,…,n.
Note: J 0-x=J 0 x, so the approximation need only consider x≥0.
The routine is based on three Chebyshev expansions:
For 0<x≤8,
J 0 x=∑′r=0 arTr t,   with ​t=2 x 8 2 -1.
For x>8,
J 0 x= 2 πx P 0 x cos x-π 4-Q 0 x sin x- π 4 ,
where P 0 x=∑′r=0 brTr t,
and Q 0 x= 8 x∑′r=0 crTr t,
with t=2 8 x 2-1.
For x near zero, J 0 x≃1. This approximation is used when x is sufficiently small for the result to be correct to machine precision.
For very large x, it becomes impossible to provide results with any reasonable accuracy (see Section 7), hence the routine fails. Such arguments contain insufficient information to determine the phase of oscillation of J 0 x; only the amplitude, 2 π x , can be determined and this is returned on soft failure. The range for which this occurs is roughly related to machine precision; the routine will fail if x≳1/machine precision (see the Users' Note for your implementation for details).

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Clenshaw C W (1962) Chebyshev Series for Mathematical Functions Mathematical tables HMSO

5 Arguments

1:   N – INTEGERInput
On entry: n, the number of points.
Constraint: N≥0.
2:   X N – REAL (KIND=nag_wp) arrayInput
On entry: the argument xi of the function, for i=1,2,…,N.
3:   F N – REAL (KIND=nag_wp) arrayOutput
On exit: J 0 xi, the function values.
4:   IVALID N – INTEGER arrayOutput
On exit: IVALID i contains the error code for xi, for i=1,2,…,N.
IVALID i=0
No error.
IVALID i=1
On entry, xi is too large. F i contains the amplitude of the J 0 oscillation, 2 π xi .
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, at least one value of X was invalid.
Check IVALID for more information.
IFAIL=2
On entry, N=value.
Constraint: N≥0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Let δ be the relative error in the argument and E be the absolute error in the result. (Since J 0 x oscillates about zero, absolute error and not relative error is significant.)
If δ is somewhat larger than the machine precision (e.g., if δ is due to data errors etc.), then E and δ are approximately related by:
E≃x J 1 x δ
(provided E is also within machine bounds). Figure 1 displays the behaviour of the amplification factor x J 1 x.
However, if δ is of the same order as machine precision, then rounding errors could make E slightly larger than the above relation predicts.
For very large x, the above relation ceases to apply. In this region, J 0 x≃ 2 π x cos x- π 4. The amplitude 2 π x can be calculated with reasonable accuracy for all x, but cos x- π 4 cannot. If x- π 4 is written as 2 Nπ+θ where N is an integer and 0≤θ<2 π, then cos x- π 4 is determined by θ only. If x≳δ-1, θ cannot be determined with any accuracy at all. Thus if x is greater than, or of the order of, the inverse of the machine precision, it is impossible to calculate the phase of J 0 x and the routine must fail.
Figure 1

8 Parallelism and Performance

S17ASF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of X from a file, evaluates the function at each value of xi and prints the results.

10.1 Program Text

Program Text (s17asfe.f90)

10.2 Program Data

Program Data (s17asfe.d)

10.3 Program Results

Program Results (s17asfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S17ATF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S17ATF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S17ATF returns an array of values of the Bessel function J 1 x.

2 Specification

SUBROUTINE S17ATF ( N, X, F, IVALID, IFAIL)
INTEGER | N, IVALID(N), IFAIL
REAL (KIND=nag_wp) | X(N), F(N)

3 Description

S17ATF evaluates an approximation to the Bessel function of the first kind J 1 xi for an array of arguments xi, for i=1,2,…,n.
Note: J 1-x=-J 1 x, so the approximation need only consider x≥0.
The routine is based on three Chebyshev expansions:
For 0<x≤8,
J 1 x=x 8∑′r=0 arTr t,   with ​t=2 x 8 2-1.
For x>8,
J 1 x=2 πx P 1 x cos x-3 π 4-Q 1 x sin x-3 π 4
where P 1 x=∑′r=0 brTr t,
and Q 1 x= 8 x∑′r=0 crTr t,
with t=2 8 x 2-1.
For x near zero, J 1 x≃ x 2 . This approximation is used when x is sufficiently small for the result to be correct to machine precision.
For very large x, it becomes impossible to provide results with any reasonable accuracy (see Section 7), hence the routine fails. Such arguments contain insufficient information to determine the phase of oscillation of J 1 x; only the amplitude, 2 π x , can be determined and this is returned on soft failure. The range for which this occurs is roughly related to machine precision; the routine will fail if x≳1/machine precision (see the Users' Note for your implementation for details).

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Clenshaw C W (1962) Chebyshev Series for Mathematical Functions Mathematical tables HMSO

5 Arguments

1:   N – INTEGERInput
On entry: n, the number of points.
Constraint: N≥0.
2:   X N – REAL (KIND=nag_wp) arrayInput
On entry: the argument xi of the function, for i=1,2,…,N.
3:   F N – REAL (KIND=nag_wp) arrayOutput
On exit: J 1 xi, the function values.
4:   IVALID N – INTEGER arrayOutput
On exit: IVALID i contains the error code for xi, for i=1,2,…,N.
IVALID i=0
No error.
IVALID i=1
On entry, xi is too large. F i contains the amplitude of the J 1 oscillation, 2 π xi .
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, at least one value of X was invalid.
Check IVALID for more information.
IFAIL=2
On entry, N=value.
Constraint: N≥0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Let δ be the relative error in the argument and E be the absolute error in the result. (Since J 1 x oscillates about zero, absolute error and not relative error is significant.)
If δ is somewhat larger than machine precision (e.g., if δ is due to data errors etc.), then E and δ are approximately related by:
E≃x J 0 x-J 1 x δ
(provided E is also within machine bounds). Figure 1 displays the behaviour of the amplification factor x J 0 x-J 1 x.
However, if δ is of the same order as machine precision, then rounding errors could make E slightly larger than the above relation predicts.
For very large x, the above relation ceases to apply. In this region, J 1 x≃ 2 π x cos x- 3 π 4. The amplitude 2 π x can be calculated with reasonable accuracy for all x, but cos x- 3 π 4 cannot. If x- 3 π 4 is written as 2 Nπ+θ where N is an integer and 0≤θ<2 π, then cos x- 3 π 4 is determined by θ only. If x≳δ-1, θ cannot be determined with any accuracy at all. Thus if x is greater than, or of the order of, the reciprocal of machine precision, it is impossible to calculate the phase of J 1 x and the routine must fail.
Figure 1

8 Parallelism and Performance

S17ATF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of X from a file, evaluates the function at each value of xi and prints the results.

10.1 Program Text

Program Text (s17atfe.f90)

10.2 Program Data

Program Data (s17atfe.d)

10.3 Program Results

Program Results (s17atfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S17AUF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S17AUF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S17AUF returns an array of values for the Airy function, Ai x.

2 Specification

SUBROUTINE S17AUF ( N, X, F, IVALID, IFAIL)
INTEGER | N, IVALID(N), IFAIL
REAL (KIND=nag_wp) | X(N), F(N)

3 Description

S17AUF evaluates an approximation to the Airy function, Ai xi for an array of arguments xi, for i=1,2,…,n. It is based on a number of Chebyshev expansions:
For x<-5,
Ai x=a t sin⁡z-b t cos⁡z-x 1/4
where z= π 4+ 23-x 3, and a t and b t are expansions in the variable t=-2 5 x 3-1.
For -5≤x≤0,
Ai x=f t-xg t,
where f and g are expansions in t=-2 x 5 3-1.
For 0<x<4.5,
Ai x=e-3 x/2 y t,
where y is an expansion in t=4 x/9-1.
For 4.5≤x<9,
Ai x=e-5 x/2 u t,
where u is an expansion in t=4 x/9-3.
For x≥9,
Ai x=e-z v t x 1/4,
where z= 23 x 3 and v is an expansion in t=2 18 z-1.
For x<machine precision, the result is set directly to Ai 0. This both saves time and guards against underflow in intermediate calculations.
For large negative arguments, it becomes impossible to calculate the phase of the oscillatory function with any precision and so the routine must fail. This occurs if x<- 3 2 ε 2/3 , where ε is the machine precision.
For large positive arguments, where Ai decays in an essentially exponential manner, there is a danger of underflow so the routine must fail.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   N – INTEGERInput
On entry: n, the number of points.
Constraint: N≥0.
2:   X N – REAL (KIND=nag_wp) arrayInput
On entry: the argument xi of the function, for i=1,2,…,N.
3:   F N – REAL (KIND=nag_wp) arrayOutput
On exit: Ai xi, the function values.
4:   IVALID N – INTEGER arrayOutput
On exit: IVALID i contains the error code for xi, for i=1,2,…,N.
IVALID i=0
No error.
IVALID i=1
xi is too large and positive. F i contains zero. The threshold value is the same as for IFAIL=1 in S17AGF, as defined in the Users' Note for your implementation.
IVALID i=2
xi is too large and negative. F i contains zero. The threshold value is the same as for IFAIL=2 in S17AGF, as defined in the Users' Note for your implementation.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, at least one value of X was invalid.
Check IVALID for more information.
IFAIL=2
On entry, N=value.
Constraint: N≥0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

For negative arguments the function is oscillatory and hence absolute error is the appropriate measure. In the positive region the function is essentially exponential-like and here relative error is appropriate. The absolute error, E, and the relative error, ε, are related in principle to the relative error in the argument, δ, by
E≃ x Ai′x δ, ε≃ x Ai′x Ai x δ.
In practice, approximate equality is the best that can be expected. When δ, ε or E is of the order of the machine precision, the errors in the result will be somewhat larger.
For small x, errors are strongly damped by the function and hence will be bounded by the machine precision.
For moderate negative x, the error behaviour is oscillatory but the amplitude of the error grows like
amplitude Eδ ∼x 5/4 π.
However the phase error will be growing roughly like 23 x 3 and hence all accuracy will be lost for large negative arguments due to the impossibility of calculating sin and cos to any accuracy if 23 x 3> 1 δ .
For large positive arguments, the relative error amplification is considerable:
ε δ ∼x 3.
This means a loss of roughly two decimal places accuracy for arguments in the region of 20. However very large arguments are not possible due to the danger of setting underflow and so the errors are limited in practice.

8 Parallelism and Performance

S17AUF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of X from a file, evaluates the function at each value of xi and prints the results.

10.1 Program Text

Program Text (s17aufe.f90)

10.2 Program Data

Program Data (s17aufe.d)

10.3 Program Results

Program Results (s17aufe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S17AVF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S17AVF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S17AVF returns an array of values of the Airy function, Bi x.

2 Specification

SUBROUTINE S17AVF ( N, X, F, IVALID, IFAIL)
INTEGER | N, IVALID(N), IFAIL
REAL (KIND=nag_wp) | X(N), F(N)

3 Description

S17AVF evaluates an approximation to the Airy function Bi xi for an array of arguments xi, for i=1,2,…,n. It is based on a number of Chebyshev expansions.
For x<-5,
Bi x=a t cos⁡z+b t sin⁡z-x 1/4,
where z= π 4+ 23-x 3 and a t and b t are expansions in the variable t=-2 5 x 3-1.
For -5≤x≤0,
Bi x=3 f t+xg t,
where f and g are expansions in t=-2 x 5 3-1.
For 0<x<4.5,
Bi x=e 11 x/8 y t,
where y is an expansion in t=4 x/9-1.
For 4.5≤x<9,
Bi x=e 5 x/2 v t,
where v is an expansion in t=4 x/9-3.
For x≥9,
Bi x=ez u t x 1/4,
where z= 23 x 3 and u is an expansion in t=2 18 z-1.
For x<machine precision, the result is set directly to Bi 0. This both saves time and avoids possible intermediate underflows.
For large negative arguments, it becomes impossible to calculate the phase of the oscillating function with any accuracy so the routine must fail. This occurs if x<- 3 2 ε 2/3, where ε is the machine precision.
For large positive arguments, there is a danger of causing overflow since Bi grows in an essentially exponential manner, so the routine must fail.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   N – INTEGERInput
On entry: n, the number of points.
Constraint: N≥0.
2:   X N – REAL (KIND=nag_wp) arrayInput
On entry: the argument xi of the function, for i=1,2,…,N.
3:   F N – REAL (KIND=nag_wp) arrayOutput
On exit: Bi xi, the function values.
4:   IVALID N – INTEGER arrayOutput
On exit: IVALID i contains the error code for xi, for i=1,2,…,N.
IVALID i=0
No error.
IVALID i=1
xi is too large and positive. F i contains zero. The threshold value is the same as for IFAIL=1 in S17AHF, as defined in the Users' Note for your implementation.
IVALID i=2
xi is too large and negative. F i contains zero. The threshold value is the same as for IFAIL=2 in S17AHF, as defined in the Users' Note for your implementation.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, at least one value of X was invalid.
Check IVALID for more information.
IFAIL=2
On entry, N=value.
Constraint: N≥0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

For negative arguments the function is oscillatory and hence absolute error is the appropriate measure. In the positive region the function is essentially exponential-like and here relative error is appropriate. The absolute error, E, and the relative error, ε, are related in principle to the relative error in the argument, δ, by
E≃ x Bi′x δ,ε≃ x Bi′x Bi x δ.
In practice, approximate equality is the best that can be expected. When δ, ε or E is of the order of the machine precision, the errors in the result will be somewhat larger.
For small x, errors are strongly damped and hence will be bounded essentially by the machine precision.
For moderate to large negative x, the error behaviour is clearly oscillatory but the amplitude of the error grows like amplitude Eδ ∼ x 5/4 π .
However the phase error will be growing roughly as 23 x 3 and hence all accuracy will be lost for large negative arguments. This is due to the impossibility of calculating sin and cos to any accuracy if 23 x 3> 1 δ .
For large positive arguments, the relative error amplification is considerable:
εδ∼x 3.
This means a loss of roughly two decimal places accuracy for arguments in the region of 20. However very large arguments are not possible due to the danger of causing overflow and errors are therefore limited in practice.

8 Parallelism and Performance

S17AVF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of X from a file, evaluates the function at each value of xi and prints the results.

10.1 Program Text

Program Text (s17avfe.f90)

10.2 Program Data

Program Data (s17avfe.d)

10.3 Program Results

Program Results (s17avfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S17AWF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S17AWF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S17AWF returns an array of values of the derivative of the Airy function Ai x.

2 Specification

SUBROUTINE S17AWF ( N, X, F, IVALID, IFAIL)
INTEGER | N, IVALID(N), IFAIL
REAL (KIND=nag_wp) | X(N), F(N)

3 Description

S17AWF evaluates an approximation to the derivative of the Airy function Ai xi for an array of arguments xi, for i=1,2,…,n. It is based on a number of Chebyshev expansions.
For x<-5,
Ai′x=-x 4 a t cos⁡z+b t ζ sin⁡z ,
where z= π 4+ζ, ζ= 23-x 3 and a t and b t are expansions in variable t=-2 5 x 3-1.
For -5≤x≤0,
Ai′x=x 2 f t-g t,
where f and g are expansions in t=-2 x 5 3-1.
For 0<x<4.5,
Ai′x=e-11 x/8 y t,
where y t is an expansion in t=4 x 9-1.
For 4.5≤x<9,
Ai′x=e-5 x/2 v t,
where v t is an expansion in t=4 x 9-3.
For x≥9,
Ai′x = x 4 e-z u t ,
where z= 23 x 3 and u t is an expansion in t=2 18 z-1.
For x< the square of the machine precision, the result is set directly to Ai′0. This both saves time and avoids possible intermediate underflows.
For large negative arguments, it becomes impossible to calculate a result for the oscillating function with any accuracy and so the routine must fail. This occurs for x<- π ε 4/7 , where ε is the machine precision.
For large positive arguments, where Ai′ decays in an essentially exponential manner, there is a danger of underflow so the routine must fail.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   N – INTEGERInput
On entry: n, the number of points.
Constraint: N≥0.
2:   X N – REAL (KIND=nag_wp) arrayInput
On entry: the argument xi of the function, for i=1,2,…,N.
3:   F N – REAL (KIND=nag_wp) arrayOutput
On exit: Ai′xi, the function values.
4:   IVALID N – INTEGER arrayOutput
On exit: IVALID i contains the error code for xi, for i=1,2,…,N.
IVALID i=0
No error.
IVALID i=1
xi is too large and positive. F i contains zero. The threshold value is the same as for IFAIL=1 in S17AJF, as defined in the Users' Note for your implementation.
IVALID i=2
xi is too large and negative. F i contains zero. The threshold value is the same as for IFAIL=2 in S17AJF, as defined in the Users' Note for your implementation.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, at least one value of X was invalid.
Check IVALID for more information.
IFAIL=2
On entry, N=value.
Constraint: N≥0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

For negative arguments the function is oscillatory and hence absolute error is the appropriate measure. In the positive region the function is essentially exponential in character and here relative error is needed. The absolute error, E, and the relative error, ε, are related in principle to the relative error in the argument, δ, by
E≃ x 2 Ai x δ ε≃ x 2 Ai x Ai′x δ.
In practice, approximate equality is the best that can be expected. When δ, ε or E is of the order of the machine precision, the errors in the result will be somewhat larger.
For small x, positive or negative, errors are strongly attenuated by the function and hence will be roughly bounded by the machine precision.
For moderate to large negative x, the error, like the function, is oscillatory; however the amplitude of the error grows like
x 7/4 π.
Therefore it becomes impossible to calculate the function with any accuracy if x 7/4> π δ .
For large positive x, the relative error amplification is considerable:
εδ≃x 3.
However, very large arguments are not possible due to the danger of underflow. Thus in practice error amplification is limited.

8 Parallelism and Performance

S17AWF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of X from a file, evaluates the function at each value of xi and prints the results.

10.1 Program Text

Program Text (s17awfe.f90)

10.2 Program Data

Program Data (s17awfe.d)

10.3 Program Results

Program Results (s17awfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S17AXF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S17AXF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S17AXF returns an array of values for the derivative of the Airy function Bi x.

2 Specification

SUBROUTINE S17AXF ( N, X, F, IVALID, IFAIL)
INTEGER | N, IVALID(N), IFAIL
REAL (KIND=nag_wp) | X(N), F(N)

3 Description

S17AXF calculates an approximate value for the derivative of the Airy function Bi xi for an array of arguments xi, for i=1,2,…,n. It is based on a number of Chebyshev expansions.
For x<-5,
Bi′x=-x 4 -a t sin⁡z+b t ζ cos⁡z ,
where z= π 4+ζ, ζ= 23-x 3 and a t and b t are expansions in the variable t=-2 5 x 3-1.
For -5≤x≤0,
Bi′x=3 x 2 f t+g t,
where f and g are expansions in t=-2 x 5 3-1.
For 0<x<4.5,
Bi′x=e 3 x/2 y t,
where y t is an expansion in t=4 x/9-1.
For 4.5≤x<9,
Bi′x=e 21 x/8 u t,
where u t is an expansion in t=4 x/9-3.
For x≥9,
Bi′x=x 4 ez v t,
where z= 23 x 3 and v t is an expansion in t=2 18 z-1.
For x< the square of the machine precision, the result is set directly to Bi′0. This saves time and avoids possible underflows in calculation.
For large negative arguments, it becomes impossible to calculate a result for the oscillating function with any accuracy so the routine must fail. This occurs for x<- π ε 4/7 , where ε is the machine precision.
For large positive arguments, where Bi′ grows in an essentially exponential manner, there is a danger of overflow so the routine must fail.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   N – INTEGERInput
On entry: n, the number of points.
Constraint: N≥0.
2:   X N – REAL (KIND=nag_wp) arrayInput
On entry: the argument xi of the function, for i=1,2,…,N.
3:   F N – REAL (KIND=nag_wp) arrayOutput
On exit: Bi′xi, the function values.
4:   IVALID N – INTEGER arrayOutput
On exit: IVALID i contains the error code for xi, for i=1,2,…,N.
IVALID i=0
No error.
IVALID i=1
xi is too large and positive. F i contains zero. The threshold value is the same as for IFAIL=1 in S17AKF, as defined in the Users' Note for your implementation.
IVALID i=2
xi is too large and negative. F i contains zero. The threshold value is the same as for IFAIL=2 in S17AKF, as defined in the Users' Note for your implementation.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, at least one value of X was invalid.
Check IVALID for more information.
IFAIL=2
On entry, N=value.
Constraint: N≥0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

For negative arguments the function is oscillatory and hence absolute error is appropriate. In the positive region the function has essentially exponential behaviour and hence relative error is needed. The absolute error, E, and the relative error ε, are related in principle to the relative error in the argument δ, by
E≃ x 2 Bi x δ  ε≃ x 2 Bi x Bi′x δ.
In practice, approximate equality is the best that can be expected. When δ, ε or E is of the order of the machine precision, the errors in the result will be somewhat larger.
For small x, positive or negative, errors are strongly attenuated by the function and hence will effectively be bounded by the machine precision.
For moderate to large negative x, the error is, like the function, oscillatory. However, the amplitude of the absolute error grows like x 7/4 π . Therefore it becomes impossible to calculate the function with any accuracy if x 7/4> π δ .
For large positive x, the relative error amplification is considerable: εδ∼x 3. However, very large arguments are not possible due to the danger of overflow. Thus in practice the actual amplification that occurs is limited.

8 Parallelism and Performance

S17AXF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of X from a file, evaluates the function at each value of xi and prints the results.

10.1 Program Text

Program Text (s17axfe.f90)

10.2 Program Data

Program Data (s17axfe.d)

10.3 Program Results

Program Results (s17axfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S17DCF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S17DCF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S17DCF returns a sequence of values for the Bessel functions Y ν+n z for complex z, non-negative ν and n=0,1,…,N-1, with an option for exponential scaling.

2 Specification

SUBROUTINE S17DCF ( FNU, Z, N, SCAL, CY, NZ, CWRK, IFAIL)
INTEGER | N, NZ, IFAIL
REAL (KIND=nag_wp) | FNU
COMPLEX (KIND=nag_wp) | Z, CY(N), CWRK(N)
CHARACTER(1) | SCAL

3 Description

S17DCF evaluates a sequence of values for the Bessel function Yν z, where z is complex, -π<argz≤π, and ν is the real, non-negative order. The N-member sequence is generated for orders ν, ν+1,…,ν+N-1. Optionally, the sequence is scaled by the factor e-Im z.
Note: although the routine may not be called with ν less than zero, for negative orders the formula Y-ν z=Yν z cos πν+Jν z sin πν may be used (for the Bessel function Jν z, see S17DEF).
The routine is derived from the routine CBESY in Amos (1986). It is based on the relation Yν z= Hν 1 z-Hν 2 z 2 i , where Hν 1 z and Hν 2 z are the Hankel functions of the first and second kinds respectively (see S17DLF).
When N is greater than 1, extra values of Yν z are computed using recurrence relations.
For very large z or ν+N-1, argument reduction will cause total loss of accuracy, and so no computation is performed. For slightly smaller z or ν+N-1, the computation is performed but results are accurate to less than half of machine precision. If z is very small, near the machine underflow threshold, or ν+N-1 is too large, there is a risk of overflow and so no computation is performed. In all the above cases, a warning is given by the routine.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Amos D E (1986) Algorithm 644: A portable package for Bessel functions of a complex argument and non-negative order ACM Trans. Math. Software 12 265–273

5 Arguments

1:   FNU – REAL (KIND=nag_wp)Input
On entry: ν, the order of the first member of the sequence of functions.
Constraint: FNU≥0.0.
2:   Z – COMPLEX (KIND=nag_wp)Input
On entry: z, the argument of the functions.
Constraint: Z≠0.0,0.0.
3:   N – INTEGERInput
On entry: N, the number of members required in the sequence Yν z,Y ν+1 z,…,Y ν+N-1 z.
Constraint: N≥1.
4:   SCAL – CHARACTER(1)Input
On entry: the scaling option.
SCAL='U'
The results are returned unscaled.
SCAL='S'
The results are returned scaled by the factor e-Im z.
Constraint: SCAL='U' or 'S'.
5:   CY N – COMPLEX (KIND=nag_wp) arrayOutput
On exit: the N required function values: CY i contains Y ν+i-1 z , for i=1,2,…,N.
6:   NZ – INTEGEROutput
On exit: the number of components of CY that are set to zero due to underflow. The positions of such components in the array CY are arbitrary.
7:   CWRK N – COMPLEX (KIND=nag_wp) arrayWorkspace
8:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | FNU<0.0,
or | Z=0.0,0.0,
or | N>1,
or | SCAL≠'U' or 'S'.
IFAIL=2
No computation has been performed due to the likelihood of overflow, because abs Z is less than a machine-dependent threshold value (given in the Users' Note for your implementation).
IFAIL=3
No computation has been performed due to the likelihood of overflow, because FNU+N-1 is too large – how large depends on Z as well as the overflow threshold of the machine.
IFAIL=4
The computation has been performed, but the errors due to argument reduction in elementary functions make it likely that the results returned by S17DCF are accurate to less than half of machine precision. This error exit may occur if either abs Z or FNU+N-1 is greater than a machine-dependent threshold value (given in the Users' Note for your implementation).
IFAIL=5
No computation has been performed because the errors due to argument reduction in elementary functions mean that all precision in results returned by S17DCF would be lost. This error exit may occur if either abs Z or FNU+N-1 is greater than a machine-dependent threshold value (given in the Users' Note for your implementation).
IFAIL=6
No results are returned because the algorithm termination condition has not been met. This may occur because the arguments supplied to S17DCF would have caused overflow or underflow.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

All constants in S17DCF are given to approximately 18 digits of precision. Calling the number of digits of precision in the floating-point arithmetic being used t, then clearly the maximum number of correct digits in the results obtained is limited by p=min t,18. Because of errors in argument reduction when computing elementary functions inside S17DCF, the actual number of correct digits is limited, in general, by p-s, where s≈max 1,,, log 10 z, log 10⁡ν represents the number of digits lost due to the argument reduction. Thus the larger the values of z and ν, the less the precision in the result. If S17DCF is called with N>1, then computation of function values via recurrence may lead to some further small loss of accuracy.
If function values which should nominally be identical are computed by calls to S17DCF with different base values of ν and different N, the computed values may not agree exactly. Empirical tests with modest values of ν and z have shown that the discrepancy is limited to the least significant 3 – 4 digits of precision.

8 Parallelism and Performance

S17DCF is not threaded in any implementation.

9 Further Comments

The time taken for a call of S17DCF is approximately proportional to the value of N, plus a constant. In general it is much cheaper to call S17DCF with N greater than 1, rather than to make N separate calls to S17DCF.
Paradoxically, for some values of z and ν, it is cheaper to call S17DCF with a larger value of N than is required, and then discard the extra function values returned. However, it is not possible to state the precise circumstances in which this is likely to occur. It is due to the fact that the base value used to start recurrence may be calculated in different regions for different N, and the costs in each region may differ greatly.
Note that if the function required is Y 0 x or Y 1 x, i.e., ν=0.0 or 1.0, where x is real and positive, and only a single unscaled function value is required, then it may be much cheaper to call S17ACF or S17ADF respectively.

10 Example

This example prints a caption and then proceeds to read sets of data from the input data stream. The first datum is a value for the order FNU, the second is a complex value for the argument, Z, and the third is a character value to set the argument SCAL. The program calls the routine with N=2 to evaluate the function for orders FNU and FNU+1, and it prints the results. The process is repeated until the end of the input data stream is encountered.

10.1 Program Text

Program Text (s17dcfe.f90)

10.2 Program Data

Program Data (s17dcfe.d)

10.3 Program Results

Program Results (s17dcfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S17DEF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S17DEF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S17DEF returns a sequence of values for the Bessel functions J ν+n z for complex z, non-negative ν and n=0,1,…,N-1, with an option for exponential scaling.

2 Specification

SUBROUTINE S17DEF ( FNU, Z, N, SCAL, CY, NZ, IFAIL)
INTEGER | N, NZ, IFAIL
REAL (KIND=nag_wp) | FNU
COMPLEX (KIND=nag_wp) | Z, CY(N)
CHARACTER(1) | SCAL

3 Description

S17DEF evaluates a sequence of values for the Bessel function Jν z, where z is complex, -π<argz≤π, and ν is the real, non-negative order. The N-member sequence is generated for orders ν, ν+1,…,ν+N-1. Optionally, the sequence is scaled by the factor e-Im z.
Note: although the routine may not be called with ν less than zero, for negative orders the formula J-ν z=Jν z cos πν-Yν z sin πν may be used (for the Bessel function Yν z, see S17DCF).
The routine is derived from the routine CBESJ in Amos (1986). It is based on the relations Jν z=e νπi/2 Iν-iz, Im z≥0.0, and Jν z=e-νπi/2 Iν iz, Im z<0.0.
The Bessel function Iν z is computed using a variety of techniques depending on the region under consideration.
When N is greater than 1, extra values of Jν z are computed using recurrence relations.
For very large z or ν+N-1, argument reduction will cause total loss of accuracy, and so no computation is performed. For slightly smaller z or ν+N-1, the computation is performed but results are accurate to less than half of machine precision. If Im z is large, there is a risk of overflow and so no computation is performed. In all the above cases, a warning is given by the routine.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Amos D E (1986) Algorithm 644: A portable package for Bessel functions of a complex argument and non-negative order ACM Trans. Math. Software 12 265–273

5 Arguments

1:   FNU – REAL (KIND=nag_wp)Input
On entry: ν, the order of the first member of the sequence of functions.
Constraint: FNU≥0.0.
2:   Z – COMPLEX (KIND=nag_wp)Input
On entry: the argument z of the functions.
3:   N – INTEGERInput
On entry: N, the number of members required in the sequence Jν z,J ν+1 z,…,J ν+N-1 z.
Constraint: N≥1.
4:   SCAL – CHARACTER(1)Input
On entry: the scaling option.
SCAL='U'
The results are returned unscaled.
SCAL='S'
The results are returned scaled by the factor e-Im z.
Constraint: SCAL='U' or 'S'.
5:   CY N – COMPLEX (KIND=nag_wp) arrayOutput
On exit: the N required function values: CY i contains J ν+i-1 z , for i=1,2,…,N.
6:   NZ – INTEGEROutput
On exit: the number of components of CY that are set to zero due to underflow. If NZ>0, then elements CY N-NZ+1, CY N-NZ+2,…,CY N are set to zero.
7:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | FNU<0.0,
or | N<1,
or | SCAL≠'U' or 'S'.
IFAIL=2
No computation has been performed due to the likelihood of overflow, because Im⁡Z is larger than a machine-dependent threshold value (given in the Users' Note for your implementation). This error exit can only occur when SCAL='U'.
IFAIL=3
The computation has been performed, but the errors due to argument reduction in elementary functions make it likely that the results returned by S17DEF are accurate to less than half of machine precision. This error exit may occur if either abs Z or FNU+N-1 is greater than a machine-dependent threshold value (given in the Users' Note for your implementation).
IFAIL=4
No computation has been performed because the errors due to argument reduction in elementary functions mean that all precision in results returned by S17DEF would be lost. This error exit may occur when either abs Z or FNU+N-1 is greater than a machine-dependent threshold value (given in the Users' Note for your implementation).
IFAIL=5
No results are returned because the algorithm termination condition has not been met. This may occur because the arguments supplied to S17DEF would have caused overflow or underflow.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

All constants in S17DEF are given to approximately 18 digits of precision. Calling the number of digits of precision in the floating-point arithmetic being used t, then clearly the maximum number of correct digits in the results obtained is limited by p=min t,18. Because of errors in argument reduction when computing elementary functions inside S17DEF, the actual number of correct digits is limited, in general, by p-s, where s ≈ max 1, log 10 z , log 10⁡ν represents the number of digits lost due to the argument reduction. Thus the larger the values of z and ν, the less the precision in the result. If S17DEF is called with N>1, then computation of function values via recurrence may lead to some further small loss of accuracy.
If function values which should nominally be identical are computed by calls to S17DEF with different base values of ν and different N, the computed values may not agree exactly. Empirical tests with modest values of ν and z have shown that the discrepancy is limited to the least significant 3 – 4 digits of precision.

8 Parallelism and Performance

S17DEF is not threaded in any implementation.

9 Further Comments

The time taken for a call of S17DEF is approximately proportional to the value of N, plus a constant. In general it is much cheaper to call S17DEF with N greater than 1, rather than to make N separate calls to S17DEF.
Paradoxically, for some values of z and ν, it is cheaper to call S17DEF with a larger value of N than is required, and then discard the extra function values returned. However, it is not possible to state the precise circumstances in which this is likely to occur. It is due to the fact that the base value used to start recurrence may be calculated in different regions for different N, and the costs in each region may differ greatly.
Note that if the function required is J 0 x or J 1 x, i.e., ν=0.0 or 1.0, where x is real and positive, and only a single unscaled function value is required, then it may be much cheaper to call S17AEF or S17AFF respectively.

10 Example

This example prints a caption and then proceeds to read sets of data from the input data stream. The first datum is a value for the order FNU, the second is a complex value for the argument, Z, and the third is a character value to set the argument SCAL. The program calls the routine with N=2 to evaluate the function for orders FNU and FNU+1, and it prints the results. The process is repeated until the end of the input data stream is encountered.

10.1 Program Text

Program Text (s17defe.f90)

10.2 Program Data

Program Data (s17defe.d)

10.3 Program Results

Program Results (s17defe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S17DGF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S17DGF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S17DGF returns the value of the Airy function Ai z or its derivative Ai′z for complex z, with an option for exponential scaling.

2 Specification

SUBROUTINE S17DGF ( DERIV, Z, SCAL, AI, NZ, IFAIL)
INTEGER | NZ, IFAIL
COMPLEX (KIND=nag_wp) | Z, AI
CHARACTER(1) | DERIV, SCAL

3 Description

S17DGF returns a value for the Airy function Ai z or its derivative Ai′z, where z is complex, -π<argz≤π. Optionally, the value is scaled by the factor e 2 z⁢z/3.
The routine is derived from the routine CAIRY in Amos (1986). It is based on the relations Ai z= z K 1/3 w π⁢3 , and Ai′z= -z K 2/3 w π⁢3 , where Kν is the modified Bessel function and w=2 z⁢z/3.
For very large z, argument reduction will cause total loss of accuracy, and so no computation is performed. For slightly smaller z, the computation is performed but results are accurate to less than half of machine precision. If Re w is too large, and the unscaled function is required, there is a risk of overflow and so no computation is performed. In all the above cases, a warning is given by the routine.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Amos D E (1986) Algorithm 644: A portable package for Bessel functions of a complex argument and non-negative order ACM Trans. Math. Software 12 265–273

5 Arguments

1:   DERIV – CHARACTER(1)Input
On entry: specifies whether the function or its derivative is required.
DERIV='F'
Ai z is returned.
DERIV='D'
Ai′z is returned.
Constraint: DERIV='F' or 'D'.
2:   Z – COMPLEX (KIND=nag_wp)Input
On entry: the argument z of the function.
3:   SCAL – CHARACTER(1)Input
On entry: the scaling option.
SCAL='U'
The result is returned unscaled.
SCAL='S'
The result is returned scaled by the factor e 2 z⁢z/3.
Constraint: SCAL='U' or 'S'.
4:   AI – COMPLEX (KIND=nag_wp)Output
On exit: the required function or derivative value.
5:   NZ – INTEGEROutput
On exit: indicates whether or not AI is set to zero due to underflow. This can only occur when SCAL='U'.
NZ=0
AI is not set to zero.
NZ=1
AI is set to zero.
6:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | DERIV≠'F' or 'D'.
or | SCAL≠'U' or 'S'.
IFAIL=2
No computation has been performed due to the likelihood of overflow, because Re w is too large, where w=2⁢Z Z/3 – how large depends on Z and the overflow threshold of the machine. This error exit can only occur when SCAL='U'.
IFAIL=3
The computation has been performed, but the errors due to argument reduction in elementary functions make it likely that the result returned by S17DGF is accurate to less than half of machine precision. This error exit may occur if abs Z is greater than a machine-dependent threshold value (given in the Users' Note for your implementation).
IFAIL=4
No computation has been performed because the errors due to argument reduction in elementary functions mean that all precision in the result returned by S17DGF would be lost. This error exit may occur if abs Z is greater than a machine-dependent threshold value (given in the Users' Note for your implementation).
IFAIL=5
No result is returned because the algorithm termination condition has not been met. This may occur because the arguments supplied to S17DGF would have caused overflow or underflow.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

All constants in S17DGF are given to approximately 18 digits of precision. Calling the number of digits of precision in the floating-point arithmetic being used t, then clearly the maximum number of correct digits in the results obtained is limited by p=min t,18. Because of errors in argument reduction when computing elementary functions inside S17DGF, the actual number of correct digits is limited, in general, by p-s, where s≈ max 1, log 10 z represents the number of digits lost due to the argument reduction. Thus the larger the value of z, the less the precision in the result.
Empirical tests with modest values of z, checking relations between Airy functions Ai z, Ai′z, Bi z and Bi′z, have shown errors limited to the least significant 3 – 4 digits of precision.

8 Parallelism and Performance

S17DGF is not threaded in any implementation.

9 Further Comments

Note that if the function is required to operate on a real argument only, then it may be much cheaper to call S17AGF or S17AJF.

10 Example

This example prints a caption and then proceeds to read sets of data from the input data stream. The first datum is a value for the argument DERIV, the second is a complex value for the argument, Z, and the third is a character value to set the argument SCAL. The program calls the routine and prints the results. The process is repeated until the end of the input data stream is encountered.

10.1 Program Text

Program Text (s17dgfe.f90)

10.2 Program Data

Program Data (s17dgfe.d)

10.3 Program Results

Program Results (s17dgfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S17DHF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S17DHF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S17DHF returns the value of the Airy function Bi z or its derivative Bi′z for complex z, with an option for exponential scaling.

2 Specification

SUBROUTINE S17DHF ( DERIV, Z, SCAL, BI, IFAIL)
INTEGER | IFAIL
COMPLEX (KIND=nag_wp) | Z, BI
CHARACTER(1) | DERIV, SCAL

3 Description

S17DHF returns a value for the Airy function Bi z or its derivative Bi′z, where z is complex, -π<argz≤π. Optionally, the value is scaled by the factor e Re 2 z⁢z/3.
The routine is derived from the routine CBIRY in Amos (1986). It is based on the relations Bi z= z3 I-1/3 w+I 1/3 w, and Bi′z= z 3 I-2/3 w+I 2/3 w, where Iν is the modified Bessel function and w=2 z⁢z/3.
For very large z, argument reduction will cause total loss of accuracy, and so no computation is performed. For slightly smaller z, the computation is performed but results are accurate to less than half of machine precision. If Re z is too large, and the unscaled function is required, there is a risk of overflow and so no computation is performed. In all the above cases, a warning is given by the routine.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Amos D E (1986) Algorithm 644: A portable package for Bessel functions of a complex argument and non-negative order ACM Trans. Math. Software 12 265–273

5 Arguments

1:   DERIV – CHARACTER(1)Input
On entry: specifies whether the function or its derivative is required.
DERIV='F'
Bi z is returned.
DERIV='D'
Bi′z is returned.
Constraint: DERIV='F' or 'D'.
2:   Z – COMPLEX (KIND=nag_wp)Input
On entry: the argument z of the function.
3:   SCAL – CHARACTER(1)Input
On entry: the scaling option.
SCAL='U'
The result is returned unscaled.
SCAL='S'
The result is returned scaled by the factor e Re 2 z⁢z/3.
Constraint: SCAL='U' or 'S'.
4:   BI – COMPLEX (KIND=nag_wp)Output
On exit: the required function or derivative value.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | DERIV≠'F' or 'D'.
or | SCAL≠'U' or 'S'.
IFAIL=2
No computation has been performed due to the likelihood of overflow, because real(Z) is too large – how large depends on the overflow threshold of the machine. This error exit can only occur when SCAL='U'.
IFAIL=3
The computation has been performed, but the errors due to argument reduction in elementary functions make it likely that the result returned by S17DHF is accurate to less than half of machine precision. This error exit may occur if abs Z is greater than a machine-dependent threshold value (given in the Users' Note for your implementation).
IFAIL=4
No computation has been performed because the errors due to argument reduction in elementary functions mean that all precision in the result returned by S17DHF would be lost. This error exit may occur if abs Z is greater than a machine-dependent threshold value (given in the Users' Note for your implementation).
IFAIL=5
No result is returned because the algorithm termination condition has not been met. This may occur because the arguments supplied to S17DHF would have caused overflow or underflow.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

All constants in S17DHF are given to approximately 18 digits of precision. Calling the number of digits of precision in the floating-point arithmetic being used t, then clearly the maximum number of correct digits in the results obtained is limited by p=min t,18. Because of errors in argument reduction when computing elementary functions inside S17DHF, the actual number of correct digits is limited, in general, by p-s, where s≈ max 1, log 10 z represents the number of digits lost due to the argument reduction. Thus the larger the value of z, the less the precision in the result.
Empirical tests with modest values of z, checking relations between Airy functions Ai z, Ai′z, Bi z and Bi′z, have shown errors limited to the least significant 3 – 4 digits of precision.

8 Parallelism and Performance

S17DHF is not threaded in any implementation.

9 Further Comments

Note that if the function is required to operate on a real argument only, then it may be much cheaper to call S17AHF or S17AKF.

10 Example

This example prints a caption and then proceeds to read sets of data from the input data stream. The first datum is a value for the argument DERIV, the second is a complex value for the argument, Z, and the third is a character value to set the argument SCAL. The program calls the routine and prints the results. The process is repeated until the end of the input data stream is encountered.

10.1 Program Text

Program Text (s17dhfe.f90)

10.2 Program Data

Program Data (s17dhfe.d)

10.3 Program Results

Program Results (s17dhfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S17DLF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S17DLF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S17DLF returns a sequence of values for the Hankel functions H ν+n 1 z or H ν+n 2 z for complex z, non-negative ν and n=0,1,…,N-1, with an option for exponential scaling.

2 Specification

SUBROUTINE S17DLF ( M, FNU, Z, N, SCAL, CY, NZ, IFAIL)
INTEGER | M, N, NZ, IFAIL
REAL (KIND=nag_wp) | FNU
COMPLEX (KIND=nag_wp) | Z, CY(N)
CHARACTER(1) | SCAL

3 Description

S17DLF evaluates a sequence of values for the Hankel function Hν 1 z or Hν 2 z, where z is complex, -π<argz≤π, and ν is the real, non-negative order. The N-member sequence is generated for orders ν, ν+1,…,ν+N-1. Optionally, the sequence is scaled by the factor e-iz if the function is Hν 1 z or by the factor e iz if the function is Hν 2 z.
Note: although the routine may not be called with ν less than zero, for negative orders the formulae H-ν 1 z=e νπi Hν 1 z, and H-ν 2 z=e-νπi Hν 2 z may be used.
The routine is derived from the routine CBESH in Amos (1986). It is based on the relation
Hν m z=1 p e-pν Kν z e-p,
where p= iπ 2 if m=1 and p=- iπ 2 if m=2, and the Bessel function Kν z is computed in the right half-plane only. Continuation of Kν z to the left half-plane is computed in terms of the Bessel function Iν z. These functions are evaluated using a variety of different techniques, depending on the region under consideration.
When N is greater than 1, extra values of Hν m z are computed using recurrence relations.
For very large z or ν+N-1, argument reduction will cause total loss of accuracy, and so no computation is performed. For slightly smaller z or ν+N-1, the computation is performed but results are accurate to less than half of machine precision. If z is very small, near the machine underflow threshold, or ν+N-1 is too large, there is a risk of overflow and so no computation is performed. In all the above cases, a warning is given by the routine.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Amos D E (1986) Algorithm 644: A portable package for Bessel functions of a complex argument and non-negative order ACM Trans. Math. Software 12 265–273

5 Arguments

1:   M – INTEGERInput
On entry: the kind of functions required.
M=1
The functions are Hν 1 z.
M=2
The functions are Hν 2 z.
Constraint: M=1 or 2.
2:   FNU – REAL (KIND=nag_wp)Input
On entry: ν, the order of the first member of the sequence of functions.
Constraint: FNU≥0.0.
3:   Z – COMPLEX (KIND=nag_wp)Input
On entry: the argument z of the functions.
Constraint: Z≠0.0,0.0.
4:   N – INTEGERInput
On entry: N, the number of members required in the sequence Hν M z,H ν+1 M z,…,H ν+N-1 M z.
Constraint: N≥1.
5:   SCAL – CHARACTER(1)Input
On entry: the scaling option.
SCAL='U'
The results are returned unscaled.
SCAL='S'
The results are returned scaled by the factor e-iz when M=1, or by the factor e iz when M=2.
Constraint: SCAL='U' or 'S'.
6:   CY N – COMPLEX (KIND=nag_wp) arrayOutput
On exit: the N required function values: CY i contains H ν+i-1 M z , for i=1,2,…,N.
7:   NZ – INTEGEROutput
On exit: the number of components of CY that are set to zero due to underflow. If NZ>0, then if Im z>0.0 and M=1, or Im z<0.0 and M=2, elements CY 1,CY 2,…,CY NZ are set to zero. In the complementary half-planes, NZ simply states the number of underflows, and not which elements they are.
8:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | M≠1 and M≠2,
or | FNU<0.0,
or | Z=0.0,0.0,
or | N<1,
or | SCAL≠'U' or 'S'.
IFAIL=2
No computation has been performed due to the likelihood of overflow, because abs Z is less than a machine-dependent threshold value (given in the Users' Note for your implementation).
IFAIL=3
No computation has been performed due to the likelihood of overflow, because FNU+N-1 is too large – how large depends on Z and the overflow threshold of the machine.
IFAIL=4
The computation has been performed, but the errors due to argument reduction in elementary functions make it likely that the results returned by S17DLF are accurate to less than half of machine precision. This error exit may occur if either abs Z or FNU+N-1 is greater than a machine-dependent threshold value (given in the Users' Note for your implementation).
IFAIL=5
No computation has been performed because the errors due to argument reduction in elementary functions mean that all precision in results returned by S17DLF would be lost. This error exit may occur when either of abs Z or FNU+N-1 is greater than a machine-dependent threshold value (given in the Users' Note for your implementation).
IFAIL=6
No results are returned because the algorithm termination condition has not been met. This may occur because the arguments supplied to S17DLF would have caused overflow or underflow.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

All constants in S17DLF are given to approximately 18 digits of precision. Calling the number of digits of precision in the floating-point arithmetic being used t, then clearly the maximum number of correct digits in the results obtained is limited by p=min t,18. Because of errors in argument reduction when computing elementary functions inside S17DLF, the actual number of correct digits is limited, in general, by p-s, where s ≈ max 1, log 10 z , log 10⁡ν represents the number of digits lost due to the argument reduction. Thus the larger the values of z and ν, the less the precision in the result. If S17DLF is called with N>1, then computation of function values via recurrence may lead to some further small loss of accuracy.
If function values which should nominally be identical are computed by calls to S17DLF with different base values of ν and different N, the computed values may not agree exactly. Empirical tests with modest values of ν and z have shown that the discrepancy is limited to the least significant 3 – 4 digits of precision.

8 Parallelism and Performance

S17DLF is not threaded in any implementation.

9 Further Comments

The time taken for a call of S17DLF is approximately proportional to the value of N, plus a constant. In general it is much cheaper to call S17DLF with N greater than 1, rather than to make N separate calls to S17DLF.
Paradoxically, for some values of z and ν, it is cheaper to call S17DLF with a larger value of N than is required, and then discard the extra function values returned. However, it is not possible to state the precise circumstances in which this is likely to occur. It is due to the fact that the base value used to start recurrence may be calculated in different regions for different N, and the costs in each region may differ greatly.

10 Example

This example prints a caption and then proceeds to read sets of data from the input data stream. The first datum is a value for the kind of function, M, the second is a value for the order FNU, the third is a complex value for the argument, Z, and the fourth is a character value to set the argument SCAL. The program calls the routine with N=2 to evaluate the function for orders FNU and FNU+1, and it prints the results. The process is repeated until the end of the input data stream is encountered.

10.1 Program Text

Program Text (s17dlfe.f90)

10.2 Program Data

Program Data (s17dlfe.d)

10.3 Program Results

Program Results (s17dlfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S18ACF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S18ACF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S18ACF returns the value of the modified Bessel function K 0 x, via the function name.

2 Specification

FUNCTION S18ACF ( X, IFAIL)
REAL (KIND=nag_wp) S18ACF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S18ACF evaluates an approximation to the modified Bessel function of the second kind K 0 x.
Note: K 0 x is undefined for x≤0 and the routine will fail for such arguments.
The routine is based on five Chebyshev expansions:
For 0<x≤1,
K 0 x=-ln⁡x∑′r=0 arTr t+∑′r=0 brTr t,   where ​t=2 x 2-1.
For 1<x≤2,
K 0 x=e-x∑′r=0 crTr t,   where ​t=2 x-3.
For 2<x≤4,
K 0 x=e-x∑′r=0 drTr t,   where ​t=x-3.
For x>4,
K 0 x=e-x x ∑′r=0 erTr t,where ​ t=9-x 1+x .
For x near zero, K 0 x≃-γ-ln x 2 , where γ denotes Euler's constant. This approximation is used when x is sufficiently small for the result to be correct to machine precision.
For large x, where there is a danger of underflow due to the smallness of K 0, the result is set exactly to zero.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
Constraint: X>0.0.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
X≤0.0, K 0 is undefined. On soft failure the routine returns zero.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Let δ and ε be the relative errors in the argument and result respectively.
If δ is somewhat larger than the machine precision (i.e., if δ is due to data errors etc.), then ε and δ are approximately related by:
ε≃ x K 1 x K 0 x δ.
Figure 1 shows the behaviour of the error amplification factor
x K 1 x K 0 x .
However, if δ is of the same order as machine precision, then rounding errors could make ε slightly larger than the above relation predicts.
For small x, the amplification factor is approximately 1 ln⁡x , which implies strong attenuation of the error, but in general ε can never be less than the machine precision.
For large x, ε≃xδ and we have strong amplification of the relative error. Eventually K 0, which is asymptotically given by e-x x , becomes so small that it cannot be calculated without underflow and hence the routine will return zero. Note that for large x the errors will be dominated by those of the standard function exp.
Figure 1

8 Parallelism and Performance

S18ACF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s18acfe.f90)

10.2 Program Data

Program Data (s18acfe.d)

10.3 Program Results

Program Results (s18acfe.r)

GnuplotProduced by GNUPLOT 4.6 patchlevel 3 0 0.5 1 1.5 2 2.5 3 3.5 4 0 0.5 1 1.5 2 2.5 3 3.5 4 K0(x) x Example Program Returned Values for the Bessel Function K0(x) gnuplot_plot_1
S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S18ADF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S18ADF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S18ADF returns the value of the modified Bessel function K 1 x, via the function name.

2 Specification

FUNCTION S18ADF ( X, IFAIL)
REAL (KIND=nag_wp) S18ADF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S18ADF evaluates an approximation to the modified Bessel function of the second kind K 1 x.
Note: K 1 x is undefined for x≤0 and the routine will fail for such arguments.
The routine is based on five Chebyshev expansions:
For 0<x≤1,
K 1 x=1 x+x ln⁡x∑′r=0 arTr t-x∑′r=0 brTr t,   where ​ t=2 x 2-1.
For 1<x≤2,
K 1 x=e-x∑′r=0 crTr t,   where ​t=2 x-3.
For 2<x≤4,
K 1 x=e-x∑′r=0 drTr t,   where ​t=x-3.
For x>4,
K 1 x=e-x x ∑′r=0 erTr t,   where ​t=9-x 1+x .
For x near zero, K 1 x≃ 1 x . This approximation is used when x is sufficiently small for the result to be correct to machine precision. For very small x on some machines, it is impossible to calculate 1 x without overflow and the routine must fail.
For large x, where there is a danger of underflow due to the smallness of K 1, the result is set exactly to zero.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
Constraint: X>0.0.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
X≤0.0, K 1 is undefined. On soft failure the routine returns zero.
IFAIL=2
X is too small, there is a danger of overflow. On soft failure the routine returns approximately the largest representable value. (see the Users' Note for your implementation for details)
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Let δ and ε be the relative errors in the argument and result respectively.
If δ is somewhat larger than the machine precision (i.e., if δ is due to data errors etc.), then ε and δ are approximately related by:
ε≃ x K 0 x- K 1 x K 1 x δ.
Figure 1 shows the behaviour of the error amplification factor
x K 0 x - K 1 x K 1 x .
However if δ is of the same order as the machine precision, then rounding errors could make ε slightly larger than the above relation predicts.
For small x, ε≃δ and there is no amplification of errors.
For large x, ε≃xδ and we have strong amplification of the relative error. Eventually K 1, which is asymptotically given by e-x x , becomes so small that it cannot be calculated without underflow and hence the routine will return zero. Note that for large x the errors will be dominated by those of the standard function exp.
Figure 1

8 Parallelism and Performance

S18ADF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s18adfe.f90)

10.2 Program Data

Program Data (s18adfe.d)

10.3 Program Results

Program Results (s18adfe.r)

GnuplotProduced by GNUPLOT 4.6 patchlevel 3 0 0.5 1 1.5 2 2.5 3 3.5 4 0 0.5 1 1.5 2 2.5 3 3.5 4 K1(x) x Example Program Returned Values for the Bessel Function K1(x) gnuplot_plot_1
S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S18AEF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S18AEF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S18AEF returns the value of the modified Bessel function I 0 x, via the function name.

2 Specification

FUNCTION S18AEF ( X, IFAIL)
REAL (KIND=nag_wp) S18AEF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S18AEF evaluates an approximation to the modified Bessel function of the first kind I 0 x.
Note: I 0-x=I 0 x, so the approximation need only consider x≥0.
The routine is based on three Chebyshev expansions:
For 0<x≤4,
I 0 x=ex∑′r=0 arTr t,   where ​ t=2 x 4 -1.
For 4<x≤12,
I 0 x=ex∑′r=0 brTr t,   where ​ t=x-8 4.
For x>12,
I 0 x=ex x ∑′r=0 crTr t,   where ​ t=2 12 x -1.
For small x, I 0 x≃1. This approximation is used when x is sufficiently small for the result to be correct to machine precision.
For large x, the routine must fail because of the danger of overflow in calculating ex.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
X is too large. On soft failure the routine returns the approximate value of I 0 x at the nearest valid argument. (see the Users' Note for your implementation for details)
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Let δ and ε be the relative errors in the argument and result respectively.
If δ is somewhat larger than the machine precision (i.e., if δ is due to data errors etc.), then ε and δ are approximately related by:
ε≃ x I 1 x I 0 x δ.
Figure 1 shows the behaviour of the error amplification factor
x I 1 x I 0 x .
Figure 1
However if δ is of the same order as machine precision, then rounding errors could make ε slightly larger than the above relation predicts.
For small x the amplification factor is approximately x 2 2 , which implies strong attenuation of the error, but in general ε can never be less than the machine precision.
For large x, ε≃xδ and we have strong amplification of errors. However the routine must fail for quite moderate values of x, because I 0 x would overflow; hence in practice the loss of accuracy for large x is not excessive. Note that for large x the errors will be dominated by those of the standard function exp.

8 Parallelism and Performance

S18AEF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s18aefe.f90)

10.2 Program Data

Program Data (s18aefe.d)

10.3 Program Results

Program Results (s18aefe.r)

GnuplotProduced by GNUPLOT 4.6 patchlevel 3 0 2 4 6 8 10 12 0 0.5 1 1.5 2 2.5 3 3.5 4 I0(x) x Example Program Returned Values for the Bessel Function I0(x) gnuplot_plot_1
S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S18AFF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S18AFF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S18AFF returns a value for the modified Bessel function I 1 x, via the function name.

2 Specification

FUNCTION S18AFF ( X, IFAIL)
REAL (KIND=nag_wp) S18AFF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S18AFF evaluates an approximation to the modified Bessel function of the first kind I 1 x.
Note: I 1-x=-I 1 x, so the approximation need only consider x≥0.
The routine is based on three Chebyshev expansions:
For 0<x≤4,
I 1 x=x∑′r=0 arTr t,   where ​t=2 x 4 2-1;
For 4<x≤12,
I 1 x=ex∑′r=0 brTr t,   where ​t=x-8 4;
For x>12,
I 1 x=ex x ∑′r=0 crTr t,   where ​t=2 12 x -1.
For small x, I 1 x≃x. This approximation is used when x is sufficiently small for the result to be correct to machine precision.
For large x, the routine must fail because I 1 x cannot be represented without overflow.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
X is too large. On soft failure the routine returns the approximate value of I 1 x at the nearest valid argument. See also the Users' Note for your implementation.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Let δ and ε be the relative errors in the argument and result respectively.
If δ is somewhat larger than the machine precision (i.e., if δ is due to data errors etc.), then ε and δ are approximately related by:
ε≃ x I 0 x- I 1 x I 1 x δ.
Figure 1 shows the behaviour of the error amplification factor
x I 0 x - I 1 x I 1 x .
Figure 1
However, if δ is of the same order as machine precision, then rounding errors could make ε slightly larger than the above relation predicts.
For small x, ε≃δ and there is no amplification of errors.
For large x, ε≃xδ and we have strong amplification of errors. However the routine must fail for quite moderate values of x because I 1 x would overflow; hence in practice the loss of accuracy for large x is not excessive. Note that for large x, the errors will be dominated by those of the standard function exp.

8 Parallelism and Performance

S18AFF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s18affe.f90)

10.2 Program Data

Program Data (s18affe.d)

10.3 Program Results

Program Results (s18affe.r)

GnuplotProduced by GNUPLOT 4.6 patchlevel 3 0 2 4 6 8 10 0 0.5 1 1.5 2 2.5 3 3.5 4 I1(x) x Example Program Returned Values for the Bessel Function I1(x) gnuplot_plot_1
S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S18AQF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S18AQF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S18AQF returns an array of values of the modified Bessel function K 0 x.

2 Specification

SUBROUTINE S18AQF ( N, X, F, IVALID, IFAIL)
INTEGER | N, IVALID(N), IFAIL
REAL (KIND=nag_wp) | X(N), F(N)

3 Description

S18AQF evaluates an approximation to the modified Bessel function of the second kind K 0 xi for an array of arguments xi, for i=1,2,…,n.
Note: K 0 x is undefined for x≤0 and the routine will fail for such arguments.
The routine is based on five Chebyshev expansions:
For 0<x≤1,
K 0 x=-ln⁡x∑′r=0 arTr t+∑′r=0 brTr t,   where ​t=2 x 2-1.
For 1<x≤2,
K 0 x=e-x∑′r=0 crTr t,   where ​t=2 x-3.
For 2<x≤4,
K 0 x=e-x∑′r=0 drTr t,   where ​t=x-3.
For x>4,
K 0 x=e-x x ∑′r=0 erTr t,where ​ t=9-x 1+x .
For x near zero, K 0 x≃-γ-ln x 2 , where γ denotes Euler's constant. This approximation is used when x is sufficiently small for the result to be correct to machine precision.
For large x, where there is a danger of underflow due to the smallness of K 0, the result is set exactly to zero.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   N – INTEGERInput
On entry: n, the number of points.
Constraint: N≥0.
2:   X N – REAL (KIND=nag_wp) arrayInput
On entry: the argument xi of the function, for i=1,2,…,N.
Constraint: X i>0.0, for i=1,2,…,N.
3:   F N – REAL (KIND=nag_wp) arrayOutput
On exit: K 0 xi, the function values.
4:   IVALID N – INTEGER arrayOutput
On exit: IVALID i contains the error code for xi, for i=1,2,…,N.
IVALID i=0
No error.
IVALID i=1
xi≤0.0, K 0 xi is undefined. F i contains 0.0.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, at least one value of X was invalid.
Check IVALID for more information.
IFAIL=2
On entry, N=value.
Constraint: N≥0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Let δ and ε be the relative errors in the argument and result respectively.
If δ is somewhat larger than the machine precision (i.e., if δ is due to data errors etc.), then ε and δ are approximately related by:
ε≃ x K 1 x K 0 x δ.
Figure 1 shows the behaviour of the error amplification factor
x K 1 x K 0 x .
However, if δ is of the same order as machine precision, then rounding errors could make ε slightly larger than the above relation predicts.
For small x, the amplification factor is approximately 1 ln⁡x , which implies strong attenuation of the error, but in general ε can never be less than the machine precision.
For large x, ε≃xδ and we have strong amplification of the relative error. Eventually K 0, which is asymptotically given by e-x x , becomes so small that it cannot be calculated without underflow and hence the routine will return zero. Note that for large x the errors will be dominated by those of the standard function exp.
Figure 1

8 Parallelism and Performance

S18AQF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of X from a file, evaluates the function at each value of xi and prints the results.

10.1 Program Text

Program Text (s18aqfe.f90)

10.2 Program Data

Program Data (s18aqfe.d)

10.3 Program Results

Program Results (s18aqfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S18ARF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S18ARF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S18ARF returns an array of values of the modified Bessel function K 1 x.

2 Specification

SUBROUTINE S18ARF ( N, X, F, IVALID, IFAIL)
INTEGER | N, IVALID(N), IFAIL
REAL (KIND=nag_wp) | X(N), F(N)

3 Description

S18ARF evaluates an approximation to the modified Bessel function of the second kind K 1 xi for an array of arguments xi, for i=1,2,…,n.
Note: K 1 x is undefined for x≤0 and the routine will fail for such arguments.
The routine is based on five Chebyshev expansions:
For 0<x≤1,
K 1 x=1 x+x ln⁡x∑′r=0 arTr t-x∑′r=0 brTr t,   where ​ t=2 x 2-1.
For 1<x≤2,
K 1 x=e-x∑′r=0 crTr t,   where ​t=2 x-3.
For 2<x≤4,
K 1 x=e-x∑′r=0 drTr t,   where ​t=x-3.
For x>4,
K 1 x=e-x x ∑′r=0 erTr t,   where ​t=9-x 1+x .
For x near zero, K 1 x≃ 1 x . This approximation is used when x is sufficiently small for the result to be correct to machine precision. For very small x it is impossible to calculate 1 x without overflow and the routine must fail.
For large x, where there is a danger of underflow due to the smallness of K 1, the result is set exactly to zero.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   N – INTEGERInput
On entry: n, the number of points.
Constraint: N≥0.
2:   X N – REAL (KIND=nag_wp) arrayInput
On entry: the argument xi of the function, for i=1,2,…,N.
Constraint: X i>0.0, for i=1,2,…,N.
3:   F N – REAL (KIND=nag_wp) arrayOutput
On exit: K 1 xi, the function values.
4:   IVALID N – INTEGER arrayOutput
On exit: IVALID i contains the error code for xi, for i=1,2,…,N.
IVALID i=0
No error.
IVALID i=1
xi≤0.0, K 1 xi is undefined. F i contains 0.0.
IVALID i=2
xi is too small, there is a danger of overflow. F i contains zero. The threshold value is the same as for IFAIL=2 in S18ADF, as defined in the Users' Note for your implementation.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, at least one value of X was invalid.
Check IVALID for more information.
IFAIL=2
On entry, N=value.
Constraint: N≥0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Let δ and ε be the relative errors in the argument and result respectively.
If δ is somewhat larger than the machine precision (i.e., if δ is due to data errors etc.), then ε and δ are approximately related by:
ε≃ x K 0 x- K 1 x K 1 x δ.
Figure 1 shows the behaviour of the error amplification factor
x K 0 x - K 1 x K 1 x .
However if δ is of the same order as the machine precision, then rounding errors could make ε slightly larger than the above relation predicts.
For small x, ε≃δ and there is no amplification of errors.
For large x, ε≃xδ and we have strong amplification of the relative error. Eventually K 1, which is asymptotically given by e-x x , becomes so small that it cannot be calculated without underflow and hence the routine will return zero. Note that for large x the errors will be dominated by those of the standard function exp.
Figure 1

8 Parallelism and Performance

S18ARF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of X from a file, evaluates the function at each value of xi and prints the results.

10.1 Program Text

Program Text (s18arfe.f90)

10.2 Program Data

Program Data (s18arfe.d)

10.3 Program Results

Program Results (s18arfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S18ASF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S18ASF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S18ASF returns an array of values of the modified Bessel function I 0 x.

2 Specification

SUBROUTINE S18ASF ( N, X, F, IVALID, IFAIL)
INTEGER | N, IVALID(N), IFAIL
REAL (KIND=nag_wp) | X(N), F(N)

3 Description

S18ASF evaluates an approximation to the modified Bessel function of the first kind I 0 xi for an array of arguments xi, for i=1,2,…,n.
Note: I 0-x=I 0 x, so the approximation need only consider x≥0.
The routine is based on three Chebyshev expansions:
For 0<x≤4,
I 0 x=ex∑′r=0 arTr t,   where ​ t=2 x 4 -1.
For 4<x≤12,
I 0 x=ex∑′r=0 brTr t,   where ​ t=x-8 4.
For x>12,
I 0 x=ex x ∑′r=0 crTr t,   where ​ t=2 12 x -1.
For small x, I 0 x≃1. This approximation is used when x is sufficiently small for the result to be correct to machine precision.
For large x, the routine must fail because of the danger of overflow in calculating ex.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   N – INTEGERInput
On entry: n, the number of points.
Constraint: N≥0.
2:   X N – REAL (KIND=nag_wp) arrayInput
On entry: the argument xi of the function, for i=1,2,…,N.
3:   F N – REAL (KIND=nag_wp) arrayOutput
On exit: I 0 xi, the function values.
4:   IVALID N – INTEGER arrayOutput
On exit: IVALID i contains the error code for xi, for i=1,2,…,N.
IVALID i=0
No error.
IVALID i=1
xi is too large. F i contains the approximate value of I 0 xi at the nearest valid argument. The threshold value is the same as for IFAIL=1 in S18AEF, as defined in the Users' Note for your implementation.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, at least one value of X was invalid.
Check IVALID for more information.
IFAIL=2
On entry, N=value.
Constraint: N≥0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Let δ and ε be the relative errors in the argument and result respectively.
If δ is somewhat larger than the machine precision (i.e., if δ is due to data errors etc.), then ε and δ are approximately related by:
ε≃ x I 1 x I 0 x δ.
Figure 1 shows the behaviour of the error amplification factor
x I 1 x I 0 x .
Figure 1
However if δ is of the same order as machine precision, then rounding errors could make ε slightly larger than the above relation predicts.
For small x the amplification factor is approximately x 2 2 , which implies strong attenuation of the error, but in general ε can never be less than the machine precision.
For large x, ε≃xδ and we have strong amplification of errors. However, for quite moderate values of x (x>x^, the threshold value), the routine must fail because I 0 x would overflow; hence in practice the loss of accuracy for x close to x^ is not excessive and the errors will be dominated by those of the standard function exp.

8 Parallelism and Performance

S18ASF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of X from a file, evaluates the function at each value of xi and prints the results.

10.1 Program Text

Program Text (s18asfe.f90)

10.2 Program Data

Program Data (s18asfe.d)

10.3 Program Results

Program Results (s18asfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S18ATF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S18ATF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S18ATF returns an array of values for the modified Bessel function I 1 x.

2 Specification

SUBROUTINE S18ATF ( N, X, F, IVALID, IFAIL)
INTEGER | N, IVALID(N), IFAIL
REAL (KIND=nag_wp) | X(N), F(N)

3 Description

S18ATF evaluates an approximation to the modified Bessel function of the first kind I 1 xi for an array of arguments xi, for i=1,2,…,n.
Note: I 1-x=-I 1 x, so the approximation need only consider x≥0.
The routine is based on three Chebyshev expansions:
For 0<x≤4,
I 1 x=x∑′r=0 arTr t,   where ​t=2 x 4 2-1;
For 4<x≤12,
I 1 x=ex∑′r=0 brTr t,   where ​t=x-8 4;
For x>12,
I 1 x=ex x ∑′r=0 crTr t,   where ​t=2 12 x -1.
For small x, I 1 x≃x. This approximation is used when x is sufficiently small for the result to be correct to machine precision.
For large x, the routine must fail because I 1 x cannot be represented without overflow.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   N – INTEGERInput
On entry: n, the number of points.
Constraint: N≥0.
2:   X N – REAL (KIND=nag_wp) arrayInput
On entry: the argument xi of the function, for i=1,2,…,N.
3:   F N – REAL (KIND=nag_wp) arrayOutput
On exit: I 1 xi, the function values.
4:   IVALID N – INTEGER arrayOutput
On exit: IVALID i contains the error code for xi, for i=1,2,…,N.
IVALID i=0
No error.
IVALID i=1
xi is too large. F i contains the approximate value of I 1 xi at the nearest valid argument. The threshold value is the same as for IFAIL=1 in S18AFF, as defined in the Users' Note for your implementation.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, at least one value of X was invalid.
Check IVALID for more information.
IFAIL=2
On entry, N=value.
Constraint: N≥0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Let δ and ε be the relative errors in the argument and result respectively.
If δ is somewhat larger than the machine precision (i.e., if δ is due to data errors etc.), then ε and δ are approximately related by:
ε≃ x I 0 x- I 1 x I 1 x δ.
Figure 1 shows the behaviour of the error amplification factor
x I 0 x - I 1 x I 1 x .
Figure 1
However, if δ is of the same order as machine precision, then rounding errors could make ε slightly larger than the above relation predicts.
For small x, ε≃δ and there is no amplification of errors.
For large x, ε≃xδ and we have strong amplification of errors. However, for quite moderate values of x (x>x^, the threshold value), the routine must fail because I 1 x would overflow; hence in practice the loss of accuracy for x close to x^ is not excessive and the errors will be dominated by those of the standard function exp.

8 Parallelism and Performance

S18ATF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of X from a file, evaluates the function at each value of xi and prints the results.

10.1 Program Text

Program Text (s18atfe.f90)

10.2 Program Data

Program Data (s18atfe.d)

10.3 Program Results

Program Results (s18atfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S18CCF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S18CCF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S18CCF returns a value of the scaled modified Bessel function ex K 0 x via the function name.

2 Specification

FUNCTION S18CCF ( X, IFAIL)
REAL (KIND=nag_wp) S18CCF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S18CCF evaluates an approximation to ex K 0 x, where K 0 is a modified Bessel function of the second kind. The scaling factor ex removes most of the variation in K 0 x.
The routine uses the same Chebyshev expansions as S18ACF, which returns the unscaled value of K 0 x.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
Constraint: X>0.0.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, X≤0.0, K 0 is undefined.
On soft failure, S18CCF returns zero.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Relative errors in the argument are attenuated when propagated into the function value. When the accuracy of the argument is essentially limited by the machine precision, the accuracy of the function value will be similarly limited by at most a small multiple of the machine precision.

8 Parallelism and Performance

S18CCF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s18ccfe.f90)

10.2 Program Data

Program Data (s18ccfe.d)

10.3 Program Results

Program Results (s18ccfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S18CDF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S18CDF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S18CDF returns a value of the scaled modified Bessel function ex K 1 x via the function name.

2 Specification

FUNCTION S18CDF ( X, IFAIL)
REAL (KIND=nag_wp) S18CDF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S18CDF evaluates an approximation to ex K 1 x, where K 1 is a modified Bessel function of the second kind. The scaling factor ex removes most of the variation in K 1 x.
The routine uses the same Chebyshev expansions as S18ADF, which returns the unscaled value of K 1 x.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
Constraint: X>0.0.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, X≤0.0: K 1 is undefined. On soft failure S18CDF returns zero.
IFAIL=2
On entry, X is too close to zero, as determined by the value of the safe-range parameter X02AMF: there is a danger of causing overflow. On soft failure, S18CDF returns the reciprocal of the safe-range parameter.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Relative errors in the argument are attenuated when propagated into the function value. When the accuracy of the argument is essentially limited by the machine precision, the accuracy of the function value will be similarly limited by at most a small multiple of the machine precision.

8 Parallelism and Performance

S18CDF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s18cdfe.f90)

10.2 Program Data

Program Data (s18cdfe.d)

10.3 Program Results

Program Results (s18cdfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S18CEF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S18CEF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S18CEF returns a value of the scaled modified Bessel function e-x I 0 x via the function name.

2 Specification

FUNCTION S18CEF ( X, IFAIL)
REAL (KIND=nag_wp) S18CEF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S18CEF evaluates an approximation to e-x I 0 x, where I 0 is a modified Bessel function of the first kind. The scaling factor e-x removes most of the variation in I 0 x.
The routine uses the same Chebyshev expansions as S18AEF, which returns the unscaled value of I 0 x.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

There are no actual failure exits from this routine. IFAIL is always set to zero. This argument is included for compatibility with other routines in this chapter.

7 Accuracy

Relative errors in the argument are attenuated when propagated into the function value. When the accuracy of the argument is essentially limited by the machine precision, the accuracy of the function value will be similarly limited by at most a small multiple of the machine precision.

8 Parallelism and Performance

S18CEF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s18cefe.f90)

10.2 Program Data

Program Data (s18cefe.d)

10.3 Program Results

Program Results (s18cefe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S18CFF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S18CFF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S18CFF returns a value of the scaled modified Bessel function e-x I 1 x via the routine name.

2 Specification

FUNCTION S18CFF ( X, IFAIL)
REAL (KIND=nag_wp) S18CFF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S18CFF evaluates an approximation to e-x I 1 x, where I 1 is a modified Bessel function of the first kind. The scaling factor e-x removes most of the variation in I 1 x.
The routine uses the same Chebyshev expansions as S18AFF, which returns the unscaled value of I 1 x.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

There are no actual failure exits from this routine. IFAIL is always set to zero. This argument is included for compatibility with other routines in this chapter.

7 Accuracy

Relative errors in the argument are attenuated when propagated into the function value. When the accuracy of the argument is essentially limited by the machine precision, the accuracy of the function value will be similarly limited by at most a small multiple of the machine precision.

8 Parallelism and Performance

S18CFF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s18cffe.f90)

10.2 Program Data

Program Data (s18cffe.d)

10.3 Program Results

Program Results (s18cffe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S18CQF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S18CQF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S18CQF returns an array of values of the scaled modified Bessel function ex K 0 x.

2 Specification

SUBROUTINE S18CQF ( N, X, F, IVALID, IFAIL)
INTEGER | N, IVALID(N), IFAIL
REAL (KIND=nag_wp) | X(N), F(N)

3 Description

S18CQF evaluates an approximation to e xi K 0 xi, where K 0 is a modified Bessel function of the second kind for an array of arguments xi, for i=1,2,…,n. The scaling factor ex removes most of the variation in K 0 x.
The routine uses the same Chebyshev expansions as S18AQF, which returns an array of the unscaled values of K 0 x.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   N – INTEGERInput
On entry: n, the number of points.
Constraint: N≥0.
2:   X N – REAL (KIND=nag_wp) arrayInput
On entry: the argument xi of the function, for i=1,2,…,N.
Constraint: X i>0.0, for i=1,2,…,N.
3:   F N – REAL (KIND=nag_wp) arrayOutput
On exit: e xi K 0 xi, the function values.
4:   IVALID N – INTEGER arrayOutput
On exit: IVALID i contains the error code for xi, for i=1,2,…,N.
IVALID i=0
No error.
IVALID i=1
On entry, xi≤0.0, K 0 xi is undefined. F i contains 0.0.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, at least one value of X was invalid.
Check IVALID for more information.
IFAIL=2
On entry, N=value.
Constraint: N≥0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Relative errors in the argument are attenuated when propagated into the function value. When the accuracy of the argument is essentially limited by the machine precision, the accuracy of the function value will be similarly limited by at most a small multiple of the machine precision.

8 Parallelism and Performance

S18CQF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of X from a file, evaluates the function at each value of xi and prints the results.

10.1 Program Text

Program Text (s18cqfe.f90)

10.2 Program Data

Program Data (s18cqfe.d)

10.3 Program Results

Program Results (s18cqfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S18CRF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S18CRF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S18CRF returns an array of values of the scaled modified Bessel function ex K 1 x.

2 Specification

SUBROUTINE S18CRF ( N, X, F, IVALID, IFAIL)
INTEGER | N, IVALID(N), IFAIL
REAL (KIND=nag_wp) | X(N), F(N)

3 Description

S18CRF evaluates an approximation to e xi K 1 xi, where K 1 is a modified Bessel function of the second kind for an array of arguments xi, for i=1,2,…,n. The scaling factor ex removes most of the variation in K 1 x.
The routine uses the same Chebyshev expansions as S18ARF, which returns an array of the unscaled values of K 1 x.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   N – INTEGERInput
On entry: n, the number of points.
Constraint: N≥0.
2:   X N – REAL (KIND=nag_wp) arrayInput
On entry: the argument xi of the function, for i=1,2,…,N.
Constraint: X i>0.0, for i=1,2,…,N.
3:   F N – REAL (KIND=nag_wp) arrayOutput
On exit: e xi K 1 xi, the function values.
4:   IVALID N – INTEGER arrayOutput
On exit: IVALID i contains the error code for xi, for i=1,2,…,N.
IVALID i=0
No error.
IVALID i=1
On entry, xi≤0.0, K 1 xi is undefined. F i contains 0.0.
IVALID i=2
xi is too close to zero, as determined by the value of the safe-range parameter X02AMF: there is a danger of causing overflow. F i contains the reciprocal of the safe-range parameter.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, at least one value of X was invalid.
Check IVALID for more information.
IFAIL=2
On entry, N=value.
Constraint: N≥0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Relative errors in the argument are attenuated when propagated into the function value. When the accuracy of the argument is essentially limited by the machine precision, the accuracy of the function value will be similarly limited by at most a small multiple of the machine precision.

8 Parallelism and Performance

S18CRF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of X from a file, evaluates the function at each value of xi and prints the results.

10.1 Program Text

Program Text (s18crfe.f90)

10.2 Program Data

Program Data (s18crfe.d)

10.3 Program Results

Program Results (s18crfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S18CSF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S18CSF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S18CSF returns an array of values of the scaled modified Bessel function e-x I 0 x.

2 Specification

SUBROUTINE S18CSF ( N, X, F, IFAIL)
INTEGER | N, IFAIL
REAL (KIND=nag_wp) | X(N), F(N)

3 Description

S18CSF evaluates an approximation to e-xi I 0 xi, where I 0 is a modified Bessel function of the first kind for an array of arguments xi, for i=1,2,…,n. The scaling factor e-x removes most of the variation in I 0 x.
The routine uses the same Chebyshev expansions as S18ASF, which returns an array of the unscaled values of I 0 x.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   N – INTEGERInput
On entry: n, the number of points.
Constraint: N≥0.
2:   X N – REAL (KIND=nag_wp) arrayInput
On entry: the argument xi of the function, for i=1,2,…,N.
3:   F N – REAL (KIND=nag_wp) arrayOutput
On exit: e-xi I 0 xi, the function values.
4:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, N=value.
Constraint: N≥0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Relative errors in the argument are attenuated when propagated into the function value. When the accuracy of the argument is essentially limited by the machine precision, the accuracy of the function value will be similarly limited by at most a small multiple of the machine precision.

8 Parallelism and Performance

S18CSF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of X from a file, evaluates the function at each value of xi and prints the results.

10.1 Program Text

Program Text (s18csfe.f90)

10.2 Program Data

Program Data (s18csfe.d)

10.3 Program Results

Program Results (s18csfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S18CTF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S18CTF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S18CTF returns an array of values of the scaled modified Bessel function e-x I 1 x.

2 Specification

SUBROUTINE S18CTF ( N, X, F, IFAIL)
INTEGER | N, IFAIL
REAL (KIND=nag_wp) | X(N), F(N)

3 Description

S18CTF evaluates an approximation to e-xi I 1 xi, where I 1 is a modified Bessel function of the first kind for an array of arguments xi, for i=1,2,…,n. The scaling factor e-x removes most of the variation in I 1 x.
The routine uses the same Chebyshev expansions as S18ATF, which returns an array of the unscaled values of I 1 x.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   N – INTEGERInput
On entry: n, the number of points.
Constraint: N≥0.
2:   X N – REAL (KIND=nag_wp) arrayInput
On entry: the argument xi of the function, for i=1,2,…,N.
3:   F N – REAL (KIND=nag_wp) arrayOutput
On exit: e-xi I 1 xi, the function values.
4:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, N=value.
Constraint: N≥0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Relative errors in the argument are attenuated when propagated into the function value. When the accuracy of the argument is essentially limited by the machine precision, the accuracy of the function value will be similarly limited by at most a small multiple of the machine precision.

8 Parallelism and Performance

S18CTF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of X from a file, evaluates the function at each value of xi and prints the results.

10.1 Program Text

Program Text (s18ctfe.f90)

10.2 Program Data

Program Data (s18ctfe.d)

10.3 Program Results

Program Results (s18ctfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S18DCF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S18DCF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S18DCF returns a sequence of values for the modified Bessel functions K ν+n z for complex z, non-negative ν and n=0,1,…,N-1, with an option for exponential scaling.

2 Specification

SUBROUTINE S18DCF ( FNU, Z, N, SCAL, CY, NZ, IFAIL)
INTEGER | N, NZ, IFAIL
REAL (KIND=nag_wp) | FNU
COMPLEX (KIND=nag_wp) | Z, CY(N)
CHARACTER(1) | SCAL

3 Description

S18DCF evaluates a sequence of values for the modified Bessel function Kν z, where z is complex, -π<argz≤π, and ν is the real, non-negative order. The N-member sequence is generated for orders ν, ν+1,…,ν+N-1. Optionally, the sequence is scaled by the factor ez.
The routine is derived from the routine CBESK in Amos (1986).
Note: although the routine may not be called with ν less than zero, for negative orders the formula K-ν z=Kν z may be used.
When N is greater than 1, extra values of Kν z are computed using recurrence relations.
For very large z or ν+N-1, argument reduction will cause total loss of accuracy, and so no computation is performed. For slightly smaller z or ν+N-1, the computation is performed but results are accurate to less than half of machine precision. If z is very small, near the machine underflow threshold, or ν+N-1 is too large, there is a risk of overflow and so no computation is performed. In all the above cases, a warning is given by the routine.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Amos D E (1986) Algorithm 644: A portable package for Bessel functions of a complex argument and non-negative order ACM Trans. Math. Software 12 265–273

5 Arguments

1:   FNU – REAL (KIND=nag_wp)Input
On entry: ν, the order of the first member of the sequence of functions.
Constraint: FNU≥0.0.
2:   Z – COMPLEX (KIND=nag_wp)Input
On entry: the argument z of the functions.
Constraint: Z≠0.0,0.0.
3:   N – INTEGERInput
On entry: N, the number of members required in the sequence Kν z,K ν+1 z,…,K ν+N-1 z.
Constraint: N≥1.
4:   SCAL – CHARACTER(1)Input
On entry: the scaling option.
SCAL='U'
The results are returned unscaled.
SCAL='S'
The results are returned scaled by the factor ez.
Constraint: SCAL='U' or 'S'.
5:   CY N – COMPLEX (KIND=nag_wp) arrayOutput
On exit: the N required function values: CY i contains K ν+i-1 z , for i=1,2,…,N.
6:   NZ – INTEGEROutput
On exit: the number of components of CY that are set to zero due to underflow. If NZ>0 and Re z≥0.0, elements CY 1,CY 2,…,CY NZ are set to zero. If Re z<0.0, NZ simply states the number of underflows, and not which elements they are.
7:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | FNU>0.0,
or | Z=0.0,0.0,
or | N<1,
or | SCAL≠'U' or 'S'.
IFAIL=2
No computation has been performed due to the likelihood of overflow, because abs Z is less than a machine-dependent threshold value (given in the Users' Note for your implementation).
IFAIL=3
No computation has been performed due to the likelihood of overflow, because FNU+N-1 is too large – how large depends on Z and the overflow threshold of the machine.
IFAIL=4
The computation has been performed, but the errors due to argument reduction in elementary functions make it likely that the results returned by S18DCF are accurate to less than half of machine precision. This error exit may occur if either abs Z or FNU+N-1 is greater than a machine-dependent threshold value (given in the Users' Note for your implementation).
IFAIL=5
No computation has been performed because the errors due to argument reduction in elementary functions mean that all precision in results returned by S18DCF would be lost. This error exit may occur when either abs Z or FNU+N-1 is greater than a machine-dependent threshold value (given in the Users' Note for your implementation).
IFAIL=6
No results are returned because the algorithm termination condition has not been met. This may occur because the arguments supplied to S18DCF would have caused overflow or underflow.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

All constants in S18DCF are given to approximately 18 digits of precision. Calling the number of digits of precision in the floating-point arithmetic being used t, then clearly the maximum number of correct digits in the results obtained is limited by p=min t,18. Because of errors in argument reduction when computing elementary functions inside S18DCF, the actual number of correct digits is limited, in general, by p-s, where s ≈ max 1, log 10 z , log 10⁡ν represents the number of digits lost due to the argument reduction. Thus the larger the values of z and ν, the less the precision in the result. If S18DCF is called with N>1, then computation of function values via recurrence may lead to some further small loss of accuracy.
If function values which should nominally be identical are computed by calls to S18DCF with different base values of ν and different N, the computed values may not agree exactly. Empirical tests with modest values of ν and z have shown that the discrepancy is limited to the least significant 3 – 4 digits of precision.

8 Parallelism and Performance

S18DCF is not threaded in any implementation.

9 Further Comments

The time taken for a call of S18DCF is approximately proportional to the value of N, plus a constant. In general it is much cheaper to call S18DCF with N greater than 1, rather than to make N separate calls to S18DCF.
Paradoxically, for some values of z and ν, it is cheaper to call S18DCF with a larger value of N than is required, and then discard the extra function values returned. However, it is not possible to state the precise circumstances in which this is likely to occur. It is due to the fact that the base value used to start recurrence may be calculated in different regions for different N, and the costs in each region may differ greatly.
Note that if the function required is K 0 x or K 1 x, i.e., ν=0.0 or 1.0, where x is real and positive, and only a single function value is required, then it may be much cheaper to call S18ACF, S18ADF, S18CCF or S18CDF, depending on whether a scaled result is required or not.

10 Example

The example program prints a caption and then proceeds to read sets of data from the input data stream. The first datum is a value for the order FNU, the second is a complex value for the argument, Z, and the third is a character value to set the argument SCAL. The program calls the routine with N=2 to evaluate the function for orders FNU and FNU+1, and it prints the results. The process is repeated until the end of the input data stream is encountered.

10.1 Program Text

Program Text (s18dcfe.f90)

10.2 Program Data

Program Data (s18dcfe.d)

10.3 Program Results

Program Results (s18dcfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S18DEF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S18DEF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S18DEF returns a sequence of values for the modified Bessel functions I ν+n z for complex z, non-negative ν and n=0,1,…,N-1, with an option for exponential scaling.

2 Specification

SUBROUTINE S18DEF ( FNU, Z, N, SCAL, CY, NZ, IFAIL)
INTEGER | N, NZ, IFAIL
REAL (KIND=nag_wp) | FNU
COMPLEX (KIND=nag_wp) | Z, CY(N)
CHARACTER(1) | SCAL

3 Description

S18DEF evaluates a sequence of values for the modified Bessel function Iν z, where z is complex, -π<argz≤π, and ν is the real, non-negative order. The N-member sequence is generated for orders ν,ν+1,…,ν+N-1. Optionally, the sequence is scaled by the factor e-Re z.
The routine is derived from the routine CBESI in Amos (1986).
Note: although the routine may not be called with ν less than zero, for negative orders the formula I-ν z=Iν z+ 2 π sin πν Kν z may be used (for the Bessel function Kν z, see S18DCF).
When N is greater than 1, extra values of Iν z are computed using recurrence relations.
For very large z or ν+N-1, argument reduction will cause total loss of accuracy, and so no computation is performed. For slightly smaller z or ν+N-1, the computation is performed but results are accurate to less than half of machine precision. If Re z is too large and the unscaled function is required, there is a risk of overflow and so no computation is performed. In all the above cases, a warning is given by the routine.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Amos D E (1986) Algorithm 644: A portable package for Bessel functions of a complex argument and non-negative order ACM Trans. Math. Software 12 265–273

5 Arguments

1:   FNU – REAL (KIND=nag_wp)Input
On entry: ν, the order of the first member of the sequence of functions.
Constraint: FNU≥0.0.
2:   Z – COMPLEX (KIND=nag_wp)Input
On entry: the argument z of the functions.
3:   N – INTEGERInput
On entry: N, the number of members required in the sequence Iν z,I ν+1 z,…,I ν+N-1 z.
Constraint: N≥1.
4:   SCAL – CHARACTER(1)Input
On entry: the scaling option.
SCAL='U'
The results are returned unscaled.
SCAL='S'
The results are returned scaled by the factor e-Re z.
Constraint: SCAL='U' or 'S'.
5:   CY N – COMPLEX (KIND=nag_wp) arrayOutput
On exit: the N required function values: CY i contains I ν+i-1 z , for i=1,2,…,N.
6:   NZ – INTEGEROutput
On exit: the number of components of CY that are set to zero due to underflow.
If NZ>0, then elements CY N-NZ+1,CY N-NZ+2,…,CY N are set to zero.
7:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | FNU<0.0,
or | N<1,
or | SCAL≠'U' or 'S'.
IFAIL=2
No computation has been performed due to the likelihood of overflow, because real(Z) is greater than a machine-dependent threshold value (given in the Users' Note for your implementation). This error exit can only occur when SCAL='U'.
IFAIL=3
The computation has been performed, but the errors due to argument reduction in elementary functions make it likely that the results returned by S18DEF are accurate to less than half of machine precision. This error exit may occur when either abs Z or FNU+N-1 is greater than a machine-dependent threshold value (given in the Users' Note for your implementation).
IFAIL=4
No computation has been performed because the errors due to argument reduction in elementary functions mean that all precision in results returned by S18DEF would be lost. This error exit may occur when either abs Z or FNU+N-1 is greater than a machine-dependent threshold value (given in the Users' Note for your implementation).
IFAIL=5
No results are returned because the algorithm termination condition has not been met. This may occur because the arguments supplied to S18DEF would have caused overflow or underflow.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

All constants in S18DEF are given to approximately 18 digits of precision. Calling the number of digits of precision in the floating-point arithmetic being used t, then clearly the maximum number of correct digits in the results obtained is limited by p=min t,18. Because of errors in argument reduction when computing elementary functions inside S18DEF, the actual number of correct digits is limited, in general, by p-s, where s ≈ max 1,log 10 z,log 10⁡ν represents the number of digits lost due to the argument reduction. Thus the larger the values of z and ν, the less the precision in the result. If S18DEF is called with N>1, then computation of function values via recurrence may lead to some further small loss of accuracy.
If function values which should nominally be identical are computed by calls to S18DEF with different base values of ν and different N, the computed values may not agree exactly. Empirical tests with modest values of ν and z have shown that the discrepancy is limited to the least significant 3 – 4 digits of precision.

8 Parallelism and Performance

S18DEF is not threaded in any implementation.

9 Further Comments

The time taken for a call of S18DEF is approximately proportional to the value of N, plus a constant. In general it is much cheaper to call S18DEF with N greater than 1, rather than to make N separate calls to S18DEF.
Paradoxically, for some values of z and ν, it is cheaper to call S18DEF with a larger value of N than is required, and then discard the extra function values returned. However, it is not possible to state the precise circumstances in which this is likely to occur. It is due to the fact that the base value used to start recurrence may be calculated in different regions for different N, and the costs in each region may differ greatly.
Note that if the function required is I 0 x or I 1 x, i.e., ν=0.0 or 1.0, where x is real and positive, and only a single function value is required, then it may be much cheaper to call S18AEF, S18AFF, S18CEF or S18CFF, depending on whether a scaled result is required or not.

10 Example

This example prints a caption and then proceeds to read sets of data from the input data stream. The first datum is a value for the order FNU, the second is a complex value for the argument, Z, and the third is a character value to set the argument SCAL. The program calls the routine with N=2 to evaluate the function for orders FNU and FNU+1, and it prints the results. The process is repeated until the end of the input data stream is encountered.

10.1 Program Text

Program Text (s18defe.f90)

10.2 Program Data

Program Data (s18defe.d)

10.3 Program Results

Program Results (s18defe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S18GKF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S18GKF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S18GKF returns a sequence of values for the Bessel functions J α+n-1 z or J α-n+1 z for complex z, non-negative α<1 and n=1,2,…,N+1.

2 Specification

SUBROUTINE S18GKF ( Z, A, NL, B, IFAIL)
INTEGER | NL, IFAIL
REAL (KIND=nag_wp) | A
COMPLEX (KIND=nag_wp) | Z, B(abs(NL)+1)

3 Description

S18GKF evaluates a sequence of values for the Bessel function of the first kind Jα z, where z is complex and nonzero and α is the order with 0≤α<1. The N+1-member sequence is generated for orders α,α+1,…,α+N when N≥0. Note that + is replaced by - when N<0. For positive orders the routine may also be called with z=0, since Jq 0=0 when q>0. For negative orders the formula
J-q z=cos πq Jq z-sin πq Yq z
is used to generate the required sequence. The appropriate values of Jq z and Yq z are obtained by calls to S17DCF and S17DEF.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   Z – COMPLEX (KIND=nag_wp)Input
On entry: the argument z of the function.
Constraint: Z≠0.0,0.0 when NL<0.
2:   A – REAL (KIND=nag_wp)Input
On entry: the order α of the first member in the required sequence of function values.
Constraint: 0.0≤A<1.0.
3:   NL – INTEGERInput
On entry: the value of N.
Constraint: abs NL≤101.
4:   B abs NL+1 – COMPLEX (KIND=nag_wp) arrayOutput
On exit: with IFAIL=0 or 3, the required sequence of function values: B n contains J α+n-1 z if NL≥0 and J α-n+1 z otherwise, for n=1,2,…,abs NL+1.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | Z=0.0,0.0 when NL<0,
or | A<0.0,
or | A≥1.0,
or | abs NL>101.
IFAIL=2
The computation has been abandoned due to the likelihood of overflow.
IFAIL=3
The computation has been completed but some precision has been lost.
IFAIL=4
The computation has been abandoned due to total loss of precision.
IFAIL=5
The computation has been abandoned due to failure to satisfy the termination condition.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

All constants in S17DCF and S17DEF are specified to approximately 18 digits of precision. If t denotes the number of digits of precision in the floating-point arithmetic being used, then clearly the maximum number of correct digits in the results obtained is limited by p=min t,18. Because of errors in argument reduction when computing elementary functions inside S17DCF and S17DEF, the actual number of correct digits is limited, in general, by p-s, where s ≈ max 1,log 10 z,log 10 α represents the number of digits lost due to the argument reduction. Thus the larger the values of z and α, the less the precision in the result.

8 Parallelism and Performance

S18GKF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example evaluates J 0 z,J 1 z,J 2 z and J 3 z at z=0.6-0.8 i, and prints the results.

10.1 Program Text

Program Text (s18gkfe.f90)

10.2 Program Data

Program Data (s18gkfe.d)

10.3 Program Results

Program Results (s18gkfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S19AAF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S19AAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S19AAF returns a value for the Kelvin function ber⁡x via the function name.

2 Specification

FUNCTION S19AAF ( X, IFAIL)
REAL (KIND=nag_wp) S19AAF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S19AAF evaluates an approximation to the Kelvin function ber⁡x.
Note: ber-x=ber⁡x, so the approximation need only consider x≥0.0.
The routine is based on several Chebyshev expansions:
For 0≤x≤5,
ber⁡x=∑′r=0 arTr t,   with ​ t=2 x 5 4-1.
For x>5,
ber⁡x= e x/2 2 πx 1+ 1 x a t cos⁡α+ 1 x b t sin⁡α + e-x/2 2 πx 1+ 1 x c t sin⁡β+ 1 x d t cos⁡β ,
where α= x 2- π 8 , β= x 2+ π 8 ,
and a t, b t, c t, and d t are expansions in the variable t= 10 x-1.
When x is sufficiently close to zero, the result is set directly to ber⁡0=1.0.
For large x, there is a danger of the result being totally inaccurate, as the error amplification factor grows in an essentially exponential manner; therefore the routine must fail.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, abs X is too large for an accurate result to be returned. On soft failure, the routine returns zero. See also the Users' Note for your implementation.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Since the function is oscillatory, the absolute error rather than the relative error is important. Let E be the absolute error in the result and δ be the relative error in the argument. If δ is somewhat larger than the machine precision, then we have:
E≃ x 2 ber 1⁡x+ bei 1⁡x δ
(provided E is within machine bounds).
For small x the error amplification is insignificant and thus the absolute error is effectively bounded by the machine precision.
For medium and large x, the error behaviour is oscillatory and its amplitude grows like x 2 π e x/2. Therefore it is not possible to calculate the function with any accuracy when x e x/2> 2 π δ . Note that this value of x is much smaller than the minimum value of x for which the function overflows.

8 Parallelism and Performance

S19AAF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s19aafe.f90)

10.2 Program Data

Program Data (s19aafe.d)

10.3 Program Results

Program Results (s19aafe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S19ABF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S19ABF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S19ABF returns a value for the Kelvin function bei⁡x via the function name.

2 Specification

FUNCTION S19ABF ( X, IFAIL)
REAL (KIND=nag_wp) S19ABF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S19ABF evaluates an approximation to the Kelvin function bei⁡x.
Note: bei-x=bei⁡x, so the approximation need only consider x≥0.0.
The routine is based on several Chebyshev expansions:
For 0≤x≤5,
bei⁡x = x 2 4 ∑ r=0 ′ ar Tr t ,   with ​ t=2 x 5 4 - 1 ;
For x>5,
bei⁡x=e x/2 2 πx 1+1 x a t sin⁡α-1 x b t cos⁡α
+e x/2 2 π x 1+1 x c t cos⁡β-1 x d t sin⁡β
where α= x 2- π 8 , β= x 2+ π 8 ,
and a t, b t, c t, and d t are expansions in the variable t= 10 x-1.
When x is sufficiently close to zero, the result is computed as bei⁡x= x 2 4 . If this result would underflow, the result returned is bei⁡x=0.0.
For large x, there is a danger of the result being totally inaccurate, as the error amplification factor grows in an essentially exponential manner; therefore the routine must fail.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, abs X is too large for an accurate result to be returned. On soft failure, the routine returns zero. See also the Users' Note for your implementation.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Since the function is oscillatory, the absolute error rather than the relative error is important. Let E be the absolute error in the function, and δ be the relative error in the argument. If δ is somewhat larger than the machine precision, then we have:
E≃ x 2 - ber 1⁡x+ bei 1⁡x δ
(provided E is within machine bounds).
For small x the error amplification is insignificant and thus the absolute error is effectively bounded by the machine precision.
For medium and large x, the error behaviour is oscillatory and its amplitude grows like x 2 π e x/2. Therefore it is impossible to calculate the functions with any accuracy when x e x/2> 2 π δ . Note that this value of x is much smaller than the minimum value of x for which the function overflows.

8 Parallelism and Performance

S19ABF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s19abfe.f90)

10.2 Program Data

Program Data (s19abfe.d)

10.3 Program Results

Program Results (s19abfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S19ACF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S19ACF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S19ACF returns a value for the Kelvin function ker⁡x, via the function name.

2 Specification

FUNCTION S19ACF ( X, IFAIL)
REAL (KIND=nag_wp) S19ACF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S19ACF evaluates an approximation to the Kelvin function ker⁡x.
Note: for x<0 the function is undefined and at x=0 it is infinite so we need only consider x>0.
The routine is based on several Chebyshev expansions:
For 0<x≤1,
ker⁡x=-f t log x+π 16 x 2 g t+y t
where f t, g t and y t are expansions in the variable t=2 x 4-1.
For 1<x≤3,
ker⁡x=exp-1116 x q t
where q t is an expansion in the variable t=x-2.
For x>3,
ker⁡x=π 2 x e-x/2 1+1 x c t cos⁡β-1 x d t sin⁡β
where β= x 2+ π 8 , and c t and d t are expansions in the variable t= 6 x-1.
When x is sufficiently close to zero, the result is computed as
ker⁡x=-γ-log x 2+π-38 x 2 x 2 16
and when x is even closer to zero, simply as ker⁡x=-γ-log x 2 .
For large x, ker⁡x is asymptotically given by π 2 x e-x/2 and this becomes so small that it cannot be computed without underflow and the routine fails.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
Constraint: X>0.0.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, X is too large: the result underflows. On soft failure, the routine returns zero. See also the Users' Note for your implementation.
IFAIL=2
On entry, X≤0.0: the function is undefined. On soft failure the routine returns zero.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Let E be the absolute error in the result, ε be the relative error in the result and δ be the relative error in the argument. If δ is somewhat larger than the machine precision, then we have:
E≃ x 2 ker 1⁡x+ kei 1⁡x δ,
ε ≃ x 2 ker 1⁡x + kei 1⁡x ker⁡x δ.
For very small x, the relative error amplification factor is approximately given by 1 log x , which implies a strong attenuation of relative error. However, ε in general cannot be less than the machine precision.
For small x, errors are damped by the function and hence are limited by the machine precision.
For medium and large x, the error behaviour, like the function itself, is oscillatory, and hence only the absolute accuracy for the function can be maintained. For this range of x, the amplitude of the absolute error decays like πx 2 e-x/2 which implies a strong attenuation of error. Eventually, ker⁡x, which asymptotically behaves like π 2 x e-x/2, becomes so small that it cannot be calculated without causing underflow, and the routine returns zero. Note that for large x the errors are dominated by those of the standard function exp.

8 Parallelism and Performance

S19ACF is not threaded in any implementation.

9 Further Comments

Underflow may occur for a few values of x close to the zeros of ker⁡x, below the limit which causes a failure with IFAIL=1.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s19acfe.f90)

10.2 Program Data

Program Data (s19acfe.d)

10.3 Program Results

Program Results (s19acfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S19ADF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S19ADF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S19ADF returns a value for the Kelvin function kei⁡x via the function name.

2 Specification

FUNCTION S19ADF ( X, IFAIL)
REAL (KIND=nag_wp) S19ADF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S19ADF evaluates an approximation to the Kelvin function kei⁡x.
Note: for x<0 the function is undefined, so we need only consider x≥0.
The routine is based on several Chebyshev expansions:
For 0≤x≤1,
kei⁡x=-π 4 f t+x 2 4-g t log x+v t
where f t, g t and v t are expansions in the variable t=2 x 4-1;
For 1<x≤3,
kei⁡x=exp-98 x u t
where u t is an expansion in the variable t=x-2;
For x>3,
kei⁡x=π 2 x e-x/2 1+1 x c t sin⁡β+1 x d t cos⁡β
where β= x 2+ π 8 , and c t and d t are expansions in the variable t= 6 x-1.
For x<0, the function is undefined, and hence the routine fails and returns zero.
When x is sufficiently close to zero, the result is computed as
kei⁡x=-π 4+1-γ-log x 2 x 2 4
and when x is even closer to zero simply as
kei⁡x=-π 4.
For large x, kei⁡x is asymptotically given by π 2 x e-x/2 and this becomes so small that it cannot be computed without underflow and the routine fails.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
Constraint: X≥0.0.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, X is too large: the result underflows. On soft failure, the routine returns zero. See also the Users' Note for your implementation.
IFAIL=2
On entry, X<0.0: the function is undefined. On soft failure the routine returns zero.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Let E be the absolute error in the result, and δ be the relative error in the argument. If δ is somewhat larger than the machine representation error, then we have:
E≃ x 2 - ker 1⁡x+ kei 1⁡x δ.
For small x, errors are attenuated by the function and hence are limited by the machine precision.
For medium and large x, the error behaviour, like the function itself, is oscillatory and hence only absolute accuracy of the function can be maintained. For this range of x, the amplitude of the absolute error decays like πx 2 e-x/2, which implies a strong attenuation of error. Eventually, kei⁡x, which is asymptotically given by π 2 x e-x/2,becomes so small that it cannot be calculated without causing underflow and therefore the routine returns zero. Note that for large x, the errors are dominated by those of the standard function exp.

8 Parallelism and Performance

S19ADF is not threaded in any implementation.

9 Further Comments

Underflow may occur for a few values of x close to the zeros of kei⁡x, below the limit which causes a failure with IFAIL=1.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s19adfe.f90)

10.2 Program Data

Program Data (s19adfe.d)

10.3 Program Results

Program Results (s19adfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S19ANF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S19ANF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S19ANF returns an array of values for the Kelvin function ber⁡x.

2 Specification

SUBROUTINE S19ANF ( N, X, F, IVALID, IFAIL)
INTEGER | N, IVALID(N), IFAIL
REAL (KIND=nag_wp) | X(N), F(N)

3 Description

S19ANF evaluates an approximation to the Kelvin function ber⁡xi for an array of arguments xi, for i=1,2,…,n.
Note: ber-x=ber⁡x, so the approximation need only consider x≥0.0.
The routine is based on several Chebyshev expansions:
For 0≤x≤5,
ber⁡x=∑′r=0 arTr t,   with ​ t=2 x 5 4-1.
For x>5,
ber⁡x= e x/2 2 πx 1+ 1 x a t cos⁡α + 1 x b t sin⁡α + e-x/2 2 πx 1+ 1 x c t sin⁡β+ 1 x d t cos⁡β ,
where α= x 2- π 8 , β= x 2+ π 8 ,
and a t, b t, c t, and d t are expansions in the variable t= 10 x-1.
When x is sufficiently close to zero, the result is set directly to ber⁡0=1.0.
For large x, there is a danger of the result being totally inaccurate, as the error amplification factor grows in an essentially exponential manner; therefore the routine must fail.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   N – INTEGERInput
On entry: n, the number of points.
Constraint: N≥0.
2:   X N – REAL (KIND=nag_wp) arrayInput
On entry: the argument xi of the function, for i=1,2,…,N.
3:   F N – REAL (KIND=nag_wp) arrayOutput
On exit: ber⁡xi, the function values.
4:   IVALID N – INTEGER arrayOutput
On exit: IVALID i contains the error code for xi, for i=1,2,…,N.
IVALID i=0
No error.
IVALID i=1
abs xi is too large for an accurate result to be returned. F i contains zero. The threshold value is the same as for IFAIL=1 in S19AAF, as defined in the Users' Note for your implementation.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, at least one value of X was invalid.
Check IVALID for more information.
IFAIL=2
On entry, N=value.
Constraint: N≥0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Since the function is oscillatory, the absolute error rather than the relative error is important. Let E be the absolute error in the result and δ be the relative error in the argument. If δ is somewhat larger than the machine precision, then we have:
E≃ x 2 ber 1⁡x+ bei 1⁡x δ
(provided E is within machine bounds).
For small x the error amplification is insignificant and thus the absolute error is effectively bounded by the machine precision.
For medium and large x, the error behaviour is oscillatory and its amplitude grows like x 2 π e x/2 . Therefore it is not possible to calculate the function with any accuracy when x e x/2 > 2 π δ . Note that this value of x is much smaller than the minimum value of x for which the function overflows.

8 Parallelism and Performance

S19ANF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of X from a file, evaluates the function at each value of xi and prints the results.

10.1 Program Text

Program Text (s19anfe.f90)

10.2 Program Data

Program Data (s19anfe.d)

10.3 Program Results

Program Results (s19anfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S19APF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S19APF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S19APF returns an array of values for the Kelvin function bei⁡x.

2 Specification

SUBROUTINE S19APF ( N, X, F, IVALID, IFAIL)
INTEGER | N, IVALID(N), IFAIL
REAL (KIND=nag_wp) | X(N), F(N)

3 Description

S19APF evaluates an approximation to the Kelvin function bei⁡xi for an array of arguments xi, for i=1,2,…,n.
Note: bei-x=bei⁡x, so the approximation need only consider x≥0.0.
The routine is based on several Chebyshev expansions:
For 0≤x≤5,
bei⁡x = x 2 4 ∑′r=0 ar Tr t ,   with ​ t=2 x 5 4 - 1 ;
For x>5,
bei⁡x = e x/2 2 πx 1 + 1 x a t sin⁡α - 1 x b t cos⁡α
+ e x/2 2 π x 1 + 1 x c t cos⁡β - 1 x d t sin⁡β
where α= x 2- π 8 , β= x 2+ π 8 ,
and a t, b t, c t, and d t are expansions in the variable t= 10 x-1.
When x is sufficiently close to zero, the result is computed as bei⁡x= x 2 4 . If this result would underflow, the result returned is bei⁡x=0.0.
For large x, there is a danger of the result being totally inaccurate, as the error amplification factor grows in an essentially exponential manner; therefore the routine must fail.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   N – INTEGERInput
On entry: n, the number of points.
Constraint: N≥0.
2:   X N – REAL (KIND=nag_wp) arrayInput
On entry: the argument xi of the function, for i=1,2,…,N.
3:   F N – REAL (KIND=nag_wp) arrayOutput
On exit: bei⁡xi, the function values.
4:   IVALID N – INTEGER arrayOutput
On exit: IVALID i contains the error code for xi, for i=1,2,…,N.
IVALID i=0
No error.
IVALID i=1
abs xi is too large for an accurate result to be returned. F i contains zero. The threshold value is the same as for IFAIL=1 in S19ABF, as defined in the Users' Note for your implementation.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, at least one value of X was invalid.
Check IVALID for more information.
IFAIL=2
On entry, N=value.
Constraint: N≥0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Since the function is oscillatory, the absolute error rather than the relative error is important. Let E be the absolute error in the function, and δ be the relative error in the argument. If δ is somewhat larger than the machine precision, then we have:
E≃ x 2 - ber 1⁡x+ bei 1⁡x δ
(provided E is within machine bounds).
For small x the error amplification is insignificant and thus the absolute error is effectively bounded by the machine precision.
For medium and large x, the error behaviour is oscillatory and its amplitude grows like x 2 π e x/2. Therefore it is impossible to calculate the functions with any accuracy when x e x/2> 2 π δ . Note that this value of x is much smaller than the minimum value of x for which the function overflows.

8 Parallelism and Performance

S19APF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of X from a file, evaluates the function at each value of xi and prints the results.

10.1 Program Text

Program Text (s19apfe.f90)

10.2 Program Data

Program Data (s19apfe.d)

10.3 Program Results

Program Results (s19apfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S19AQF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S19AQF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S19AQF returns an array of values for the Kelvin function ker⁡x.

2 Specification

SUBROUTINE S19AQF ( N, X, F, IVALID, IFAIL)
INTEGER | N, IVALID(N), IFAIL
REAL (KIND=nag_wp) | X(N), F(N)

3 Description

S19AQF evaluates an approximation to the Kelvin function ker⁡xi for an array of arguments xi, for i=1,2,…,n.
Note: for x<0 the function is undefined and at x=0 it is infinite so we need only consider x>0.
The routine is based on several Chebyshev expansions:
For 0<x≤1,
ker⁡x=-f t log x+π 16 x 2 g t+y t
where f t, g t and y t are expansions in the variable t=2 x 4-1.
For 1<x≤3,
ker⁡x=exp-1116 x q t
where q t is an expansion in the variable t=x-2.
For x>3,
ker⁡x=π 2 x e-x/2 1+1 x c t cos⁡β-1 x d t sin⁡β
where β= x 2+ π 8 , and c t and d t are expansions in the variable t= 6 x-1.
When x is sufficiently close to zero, the result is computed as
ker⁡x=-γ-log x 2+π-38 x 2 x 2 16
and when x is even closer to zero, simply as ker⁡x=-γ-log x 2 .
For large x, ker⁡x is asymptotically given by π 2 x e-x/2 and this becomes so small that it cannot be computed without underflow and the routine fails.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   N – INTEGERInput
On entry: n, the number of points.
Constraint: N≥0.
2:   X N – REAL (KIND=nag_wp) arrayInput
On entry: the argument xi of the function, for i=1,2,…,N.
Constraint: X i>0.0, for i=1,2,…,N.
3:   F N – REAL (KIND=nag_wp) arrayOutput
On exit: ker⁡xi, the function values.
4:   IVALID N – INTEGER arrayOutput
On exit: IVALID i contains the error code for xi, for i=1,2,…,N.
IVALID i=0
No error.
IVALID i=1
xi is too large, the result underflows. F i contains zero. The threshold value is the same as for IFAIL=1 in S19ACF, as defined in the Users' Note for your implementation.
IVALID i=2
xi≤0.0, the function is undefined. F i contains 0.0.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, at least one value of X was invalid.
Check IVALID for more information.
IFAIL=2
On entry, N=value.
Constraint: N≥0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Let E be the absolute error in the result, ε be the relative error in the result and δ be the relative error in the argument. If δ is somewhat larger than the machine precision, then we have:
E≃ x 2 ker 1⁡x+ kei 1⁡x δ,
ε ≃ x 2 ker 1⁡x + kei 1⁡x ker⁡x δ.
For very small x, the relative error amplification factor is approximately given by 1 log x , which implies a strong attenuation of relative error. However, ε in general cannot be less than the machine precision.
For small x, errors are damped by the function and hence are limited by the machine precision.
For medium and large x, the error behaviour, like the function itself, is oscillatory, and hence only the absolute accuracy for the function can be maintained. For this range of x, the amplitude of the absolute error decays like πx 2 e-x/2 which implies a strong attenuation of error. Eventually, ker⁡x, which asymptotically behaves like π 2 x e-x/2, becomes so small that it cannot be calculated without causing underflow, and the routine returns zero. Note that for large x the errors are dominated by those of the standard function exp.

8 Parallelism and Performance

S19AQF is not threaded in any implementation.

9 Further Comments

Underflow may occur for a few values of x close to the zeros of ker⁡x, below the limit which causes a failure with IFAIL=1.

10 Example

This example reads values of X from a file, evaluates the function at each value of xi and prints the results.

10.1 Program Text

Program Text (s19aqfe.f90)

10.2 Program Data

Program Data (s19aqfe.d)

10.3 Program Results

Program Results (s19aqfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S19ARF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S19ARF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S19ARF returns an array of values for the Kelvin function kei⁡x.

2 Specification

SUBROUTINE S19ARF ( N, X, F, IVALID, IFAIL)
INTEGER | N, IVALID(N), IFAIL
REAL (KIND=nag_wp) | X(N), F(N)

3 Description

S19ARF evaluates an approximation to the Kelvin function kei⁡xi for an array of arguments xi, for i=1,2,…,n.
Note: for x<0 the function is undefined, so we need only consider x≥0.
The routine is based on several Chebyshev expansions:
For 0≤x≤1,
kei⁡x=-π 4 f t+x 2 4-g t log x+v t
where f t, g t and v t are expansions in the variable t=2 x 4-1;
For 1<x≤3,
kei⁡x=exp-98 x u t
where u t is an expansion in the variable t=x-2;
For x>3,
kei⁡x=π 2 x e-x/2 1+1 x c t sin⁡β+1 x d t cos⁡β
where β= x 2+ π 8 , and c t and d t are expansions in the variable t= 6 x-1.
For x<0, the function is undefined, and hence the routine fails and returns zero.
When x is sufficiently close to zero, the result is computed as
kei⁡x=-π 4+1-γ-log x 2 x 2 4
and when x is even closer to zero simply as
kei⁡x=-π 4.
For large x, kei⁡x is asymptotically given by π 2 x e-x/2 and this becomes so small that it cannot be computed without underflow and the routine fails.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   N – INTEGERInput
On entry: n, the number of points.
Constraint: N≥0.
2:   X N – REAL (KIND=nag_wp) arrayInput
On entry: the argument xi of the function, for i=1,2,…,N.
Constraint: X i≥0.0, for i=1,2,…,N.
3:   F N – REAL (KIND=nag_wp) arrayOutput
On exit: kei⁡xi, the function values.
4:   IVALID N – INTEGER arrayOutput
On exit: IVALID i contains the error code for xi, for i=1,2,…,N.
IVALID i=0
No error.
IVALID i=1
xi is too large, the result underflows. F i contains zero. The threshold value is the same as for IFAIL=1 in S19ADF, as defined in the Users' Note for your implementation.
IVALID i=2
xi<0.0, the function is undefined. F i contains 0.0.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, at least one value of X was invalid.
Check IVALID for more information.
IFAIL=2
On entry, N=value.
Constraint: N≥0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Let E be the absolute error in the result, and δ be the relative error in the argument. If δ is somewhat larger than the machine representation error, then we have:
E≃ x 2 - ker 1⁡x+ kei 1⁡x δ.
For small x, errors are attenuated by the function and hence are limited by the machine precision.
For medium and large x, the error behaviour, like the function itself, is oscillatory and hence only absolute accuracy of the function can be maintained. For this range of x, the amplitude of the absolute error decays like πx 2 e-x/2, which implies a strong attenuation of error. Eventually, kei⁡x, which is asymptotically given by π 2 x e-x/2, becomes so small that it cannot be calculated without causing underflow and therefore the routine returns zero. Note that for large x, the errors are dominated by those of the standard function exp.

8 Parallelism and Performance

S19ARF is not threaded in any implementation.

9 Further Comments

Underflow may occur for a few values of x close to the zeros of kei⁡x, below the limit which causes a failure with IFAIL=1.

10 Example

This example reads values of X from a file, evaluates the function at each value of xi and prints the results.

10.1 Program Text

Program Text (s19arfe.f90)

10.2 Program Data

Program Data (s19arfe.d)

10.3 Program Results

Program Results (s19arfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S20ACF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S20ACF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S20ACF returns a value for the Fresnel integral S x, via the function name.

2 Specification

FUNCTION S20ACF ( X, IFAIL)
REAL (KIND=nag_wp) S20ACF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S20ACF evaluates an approximation to the Fresnel integral
S x=∫0 x sin π 2 t 2dt.
Note: S x=-S-x, so the approximation need only consider x≥0.0.
The routine is based on three Chebyshev expansions:
For 0<x≤3,
S x=x 3∑′r=0 arTr t,   with ​ t=2 x 3 4-1.
For x>3,
S x=12-f x x cos π 2 x 2-g x x 3 sin π 2 x 2 ,
where f x=∑′r=0 brTr t,
and g x=∑′r=0 crTr t,
with t=2 3 x 4-1.
For small x, S x≃ π 6 x 3. This approximation is used when x is sufficiently small for the result to be correct to machine precision. For very small x, this approximation would underflow; the result is then set exactly to zero.
For large x, f x≃ 1 π and g x≃ 1 π 2 . Therefore for moderately large x, when 1 π 2x 3 is negligible compared with 12 , the second term in the approximation for x>3 may be dropped. For very large x, when 1 πx becomes negligible, S x≃12 . However there will be considerable difficulties in calculating cos π 2 x 2 accurately before this final limiting value can be used. Since cos π 2 x 2 is periodic, its value is essentially determined by the fractional part of x 2. If x 2=N+θ where N is an integer and 0≤θ<1, then cos π 2 x 2 depends on θ and on N modulo 4. By exploiting this fact, it is possible to retain significance in the calculation of cos π 2 x 2 either all the way to the very large x limit, or at least until the integer part of x 2 is equal to the maximum integer allowed on the machine.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

There are no failure exits from S20ACF. The argument IFAIL has been included for consistency with other routines in this chapter.

7 Accuracy

Let δ and ε be the relative errors in the argument and result respectively.
If δ is somewhat larger than the machine precision (i.e., if δ is due to data errors etc.), then ε and δ are approximately related by:
ε≃ x sin π 2 x 2 S x δ.
Figure 1 shows the behaviour of the error amplification factor x sin π 2 x 2 S x .
However if δ is of the same order as the machine precision, then rounding errors could make ε slightly larger than the above relation predicts.
For small x, ε≃3 δ and hence there is only moderate amplification of relative error. Of course for very small x where the correct result would underflow and exact zero is returned, relative error-control is lost.
For moderately large values of x,
ε≃ 2 x sin π 2 x 2 δ
and the result will be subject to increasingly large amplification of errors. However the above relation breaks down for large values of x (i.e., when 1 x 2 is of the order of the machine precision); in this region the relative error in the result is essentially bounded by 2 πx .
Hence the effects of error amplification are limited and at worst the relative error loss should not exceed half the possible number of significant figures.
Figure 1

8 Parallelism and Performance

S20ACF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s20acfe.f90)

10.2 Program Data

Program Data (s20acfe.d)

10.3 Program Results

Program Results (s20acfe.r)

GnuplotProduced by GNUPLOT 4.6 patchlevel 3 −0.8 −0.6 −0.4 −0.2 0 0.2 0.4 0.6 0.8 −10 −5 0 5 10 S(x) x Example Program Returns a Value for the Fresnel Integral S(x) gnuplot_plot_1
S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S20ADF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S20ADF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S20ADF returns a value for the Fresnel integral C x, via the function name.

2 Specification

FUNCTION S20ADF ( X, IFAIL)
REAL (KIND=nag_wp) S20ADF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X

3 Description

S20ADF evaluates an approximation to the Fresnel integral
C x=∫0 x cos π 2 t 2dt.
Note: C x=-C-x, so the approximation need only consider x≥0.0.
The routine is based on three Chebyshev expansions:
For 0<x≤3,
C x=x∑′r=0 arTr t,   with ​ t=2 x 3 4-1.
For x>3,
C x=12+f x x sin π 2 x 2-g x x 3 cos π 2 x 2 ,
where f x=∑′r=0 brTr t,
and g x=∑′r=0 crTr t,
with t=2 3 x 4-1.
For small x, C x≃x. This approximation is used when x is sufficiently small for the result to be correct to machine precision.
For large x, f x≃ 1 π and g x≃ 1 π 2 . Therefore for moderately large x, when 1 π 2x 3 is negligible compared with 12 , the second term in the approximation for x>3 may be dropped. For very large x, when 1 πx becomes negligible, C x≃ 12 . However there will be considerable difficulties in calculating sin π 2 x 2 accurately before this final limiting value can be used. Since sin π 2 x 2 is periodic, its value is essentially determined by the fractional part of x 2. If x 2=N+θ, where N is an integer and 0≤θ<1, then sin π 2 x 2 depends on θ and on N modulo 4. By exploiting this fact, it is possible to retain some significance in the calculation of sin π 2 x 2 either all the way to the very large x limit, or at least until the integer part of x 2 is equal to the maximum integer allowed on the machine.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

There are no failure exits from S20ADF. The argument IFAIL has been included for consistency with other routines in this chapter.

7 Accuracy

Let δ and ε be the relative errors in the argument and result respectively.
If δ is somewhat larger than the machine precision (i.e if δ is due to data errors etc.), then ε and δ are approximately related by:
ε≃ x cos π 2 x 2 C x δ.
Figure 1 shows the behaviour of the error amplification factor x cos π 2 x 2 C x .
However, if δ is of the same order as the machine precision, then rounding errors could make ε slightly larger than the above relation predicts.
For small x, ε≃δ and there is no amplification of relative error.
For moderately large values of x,
ε≃ 2 x cos π 2 x 2 δ
and the result will be subject to increasingly large amplification of errors. However the above relation breaks down for large values of x (i.e., when 1 x 2 is of the order of the machine precision); in this region the relative error in the result is essentially bounded by 2 πx .
Hence the effects of error amplification are limited and at worst the relative error loss should not exceed half the possible number of significant figures.
Figure 1

8 Parallelism and Performance

S20ADF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

10.1 Program Text

Program Text (s20adfe.f90)

10.2 Program Data

Program Data (s20adfe.d)

10.3 Program Results

Program Results (s20adfe.r)

GnuplotProduced by GNUPLOT 4.6 patchlevel 3 −0.8 −0.6 −0.4 −0.2 0 0.2 0.4 0.6 0.8 −10 −5 0 5 10 C(x) x Example Program Fresnel Integral C(x) gnuplot_plot_1
S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S20AQF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S20AQF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S20AQF returns an array of values for the Fresnel integral S x.

2 Specification

SUBROUTINE S20AQF ( N, X, F, IFAIL)
INTEGER | N, IFAIL
REAL (KIND=nag_wp) | X(N), F(N)

3 Description

S20AQF evaluates an approximation to the Fresnel integral
S xi=∫0 xi sin π 2 t 2dt
for an array of arguments xi, for i=1,2,…,n.
Note: S x=-S-x, so the approximation need only consider x≥0.0.
The routine is based on three Chebyshev expansions:
For 0<x≤3,
S x=x 3∑′r=0 arTr t,   with ​ t=2 x 3 4-1.
For x>3,
S x=12-f x x cos π 2 x 2-g x x 3 sin π 2 x 2 ,
where f x=∑′r=0 brTr t,
and g x=∑′r=0 crTr t,
with t=2 3 x 4-1.
For small x, S x≃ π 6 x 3. This approximation is used when x is sufficiently small for the result to be correct to machine precision. For very small x, this approximation would underflow; the result is then set exactly to zero.
For large x, f x≃ 1 π and g x≃ 1 π 2 . Therefore for moderately large x, when 1 π 2x 3 is negligible compared with 12 , the second term in the approximation for x>3 may be dropped. For very large x, when 1 πx becomes negligible, S x≃12 . However there will be considerable difficulties in calculating cos π 2 x 2 accurately before this final limiting value can be used. Since cos π 2 x 2 is periodic, its value is essentially determined by the fractional part of x 2. If x 2=N+θ where N is an integer and 0≤θ<1, then cos π 2 x 2 depends on θ and on N modulo 4. By exploiting this fact, it is possible to retain significance in the calculation of cos π 2 x 2 either all the way to the very large x limit, or at least until the integer part of x 2 is equal to the maximum integer allowed on the machine.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   N – INTEGERInput
On entry: n, the number of points.
Constraint: N≥0.
2:   X N – REAL (KIND=nag_wp) arrayInput
On entry: the argument xi of the function, for i=1,2,…,N.
3:   F N – REAL (KIND=nag_wp) arrayOutput
On exit: S xi, the function values.
4:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, N=value.
Constraint: N≥0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Let δ and ε be the relative errors in the argument and result respectively.
If δ is somewhat larger than the machine precision (i.e., if δ is due to data errors etc.), then ε and δ are approximately related by:
ε≃ x sin π 2 x 2 S x δ.
Figure 1 shows the behaviour of the error amplification factor x sin π 2 x 2 S x .
However if δ is of the same order as the machine precision, then rounding errors could make ε slightly larger than the above relation predicts.
For small x, ε≃3 δ and hence there is only moderate amplification of relative error. Of course for very small x where the correct result would underflow and exact zero is returned, relative error-control is lost.
For moderately large values of x,
ε ≃ 2 x sin π 2 x 2 δ
and the result will be subject to increasingly large amplification of errors. However the above relation breaks down for large values of x (i.e., when 1 x 2 is of the order of the machine precision); in this region the relative error in the result is essentially bounded by 2 πx .
Hence the effects of error amplification are limited and at worst the relative error loss should not exceed half the possible number of significant figures.
Figure 1

8 Parallelism and Performance

S20AQF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of X from a file, evaluates the function at each value of xi and prints the results.

10.1 Program Text

Program Text (s20aqfe.f90)

10.2 Program Data

Program Data (s20aqfe.d)

10.3 Program Results

Program Results (s20aqfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S20ARF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S20ARF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S20ARF returns an array of values for the Fresnel integral C x.

2 Specification

SUBROUTINE S20ARF ( N, X, F, IFAIL)
INTEGER | N, IFAIL
REAL (KIND=nag_wp) | X(N), F(N)

3 Description

S20ARF evaluates an approximation to the Fresnel integral
C xi=∫0 xi cos π 2 t 2dt
for an array of arguments xi, for i=1,2,…,n.
Note: C x=-C-x, so the approximation need only consider x≥0.0.
The routine is based on three Chebyshev expansions:
For 0<x≤3,
C x=x∑′r=0 arTr t,   with ​ t=2 x 3 4-1.
For x>3,
C x=12+f x x sin π 2 x 2-g x x 3 cos π 2 x 2 ,
where f x=∑′r=0 brTr t,
and g x=∑′r=0 crTr t,
with t=2 3 x 4-1.
For small x, C x≃x. This approximation is used when x is sufficiently small for the result to be correct to machine precision.
For large x, f x≃ 1 π and g x≃ 1 π 2 . Therefore for moderately large x, when 1 π 2x 3 is negligible compared with 12 , the second term in the approximation for x>3 may be dropped. For very large x, when 1 πx becomes negligible, C x≃ 12 . However there will be considerable difficulties in calculating sin π 2 x 2 accurately before this final limiting value can be used. Since sin π 2 x 2 is periodic, its value is essentially determined by the fractional part of x 2. If x 2=N+θ, where N is an integer and 0≤θ<1, then sin π 2 x 2 depends on θ and on N modulo 4. By exploiting this fact, it is possible to retain some significance in the calculation of sin π 2 x 2 either all the way to the very large x limit, or at least until the integer part of x 2 is equal to the maximum integer allowed on the machine.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   N – INTEGERInput
On entry: n, the number of points.
Constraint: N≥0.
2:   X N – REAL (KIND=nag_wp) arrayInput
On entry: the argument xi of the function, for i=1,2,…,N.
3:   F N – REAL (KIND=nag_wp) arrayOutput
On exit: C xi, the function values.
4:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, N=value.
Constraint: N≥0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Let δ and ε be the relative errors in the argument and result respectively.
If δ is somewhat larger than the machine precision (i.e if δ is due to data errors etc.), then ε and δ are approximately related by:
ε≃ x cos π 2 x 2 C x δ.
Figure 1 shows the behaviour of the error amplification factor x cos π 2 x 2 C x .
However, if δ is of the same order as the machine precision, then rounding errors could make ε slightly larger than the above relation predicts.
For small x, ε≃δ and there is no amplification of relative error.
For moderately large values of x,
ε ≃ 2 x cos π 2 x 2 δ
and the result will be subject to increasingly large amplification of errors. However the above relation breaks down for large values of x (i.e., when 1 x 2 is of the order of the machine precision); in this region the relative error in the result is essentially bounded by 2 πx .
Hence the effects of error amplification are limited and at worst the relative error loss should not exceed half the possible number of significant figures.
Figure 1

8 Parallelism and Performance

S20ARF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of X from a file, evaluates the function at each value of xi and prints the results.

10.1 Program Text

Program Text (s20arfe.f90)

10.2 Program Data

Program Data (s20arfe.d)

10.3 Program Results

Program Results (s20arfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S21BAF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S21BAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S21BAF returns a value of an elementary integral, which occurs as a degenerate case of an elliptic integral of the first kind, via the function name.

2 Specification

FUNCTION S21BAF ( X, Y, IFAIL)
REAL (KIND=nag_wp) S21BAF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X, Y

3 Description

S21BAF calculates an approximate value for the integral
RC x,y = 12 ∫ 0 ∞ dt t+y . t+x
where x≥0 and y≠0.
This function, which is related to the logarithm or inverse hyperbolic functions for y<x and to inverse circular functions if x<y, arises as a degenerate form of the elliptic integral of the first kind. If y<0, the result computed is the Cauchy principal value of the integral.
The basic algorithm, which is due to Carlson (1979) and Carlson (1988), is to reduce the arguments recursively towards their mean by the system:
x 0=x y 0=y μn=xn+2 yn/3, Sn=yn-xn/3 μn λn=yn+2 xnyn x n+1=xn+λn/4, y n+1=yn+λn/4.
The quantity Sn for n=0,1,2,3,… decreases with increasing n, eventually Sn∼1/4 n. For small enough Sn the required function value can be approximated by the first few terms of the Taylor series about the mean. That is
RC x,y=1+3 Sn 2 10+Sn 3 7+3 Sn 4 8+9 Sn 5 22 /μn.
The truncation error involved in using this approximation is bounded by 16 Sn 6/1-2 Sn and the recursive process is stopped when Sn is small enough for this truncation error to be negligible compared to the machine precision.
Within the domain of definition, the function value is itself representable for all representable values of its arguments. However, for values of the arguments near the extremes the above algorithm must be modified so as to avoid causing underflows or overflows in intermediate steps. In extreme regions arguments are prescaled away from the extremes and compensating scaling of the result is done before returning to the calling program.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Carlson B C (1979) Computing elliptic integrals by duplication Numerische Mathematik 33 1–16
Carlson B C (1988) A table of elliptic integrals of the third kind Math. Comput. 51 267–280

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
2:   Y – REAL (KIND=nag_wp)Input
On entry: the arguments x and y of the function, respectively.
Constraint: X≥0.0 and Y≠0.0.
3:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, X<0.0; the function is undefined.
IFAIL=2
On entry, Y=0.0; the function is undefined.
On soft failure the routine returns zero.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

In principle the routine is capable of producing full machine precision. However round-off errors in internal arithmetic will result in slight loss of accuracy. This loss should never be excessive as the algorithm does not involve any significant amplification of round-off error. It is reasonable to assume that the result is accurate to within a small multiple of the machine precision.

8 Parallelism and Performance

S21BAF is not threaded in any implementation.

9 Further Comments

You should consult the S Chapter Introduction which shows the relationship of this function to the classical definitions of the elliptic integrals.

10 Example

This example simply generates a small set of nonextreme arguments which are used with the routine to produce the table of low accuracy results.

10.1 Program Text

Program Text (s21bafe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (s21bafe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S21BBF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S21BBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S21BBF returns a value of the symmetrised elliptic integral of the first kind, via the function name.

2 Specification

FUNCTION S21BBF ( X, Y, Z, IFAIL)
REAL (KIND=nag_wp) S21BBF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X, Y, Z

3 Description

S21BBF calculates an approximation to the integral
RF x,y,z=12∫0∞dt t+xt+yt+z
where x, y, z≥0 and at most one is zero.
The basic algorithm, which is due to Carlson (1979) and Carlson (1988), is to reduce the arguments recursively towards their mean by the rule:
  • x 0=min x,y,z,  z 0=max x,y,z,
  • y 0= remaining third intermediate value argument.
(This ordering, which is possible because of the symmetry of the function, is done for technical reasons related to the avoidance of overflow and underflow.)
μn = xn+yn+zn/3 Xn = 1-xn/μn Yn = 1-yn/μn Zn = 1-zn/μn λn = xnyn+ynzn+znxn x n+1 = xn+λn/4 y n+1 = yn+λn/4 z n+1 = zn+λn/4
εn=max Xn,Yn,Zn and the function may be approximated adequately by a fifth order power series:
RF x,y,z=1 μn 1-E 2 10+E 22 24-3 E 2E 3 44+E 3 14
where E 2=XnYn+YnZn+ZnXn, E 3=XnYnZn.
The truncation error involved in using this approximation is bounded by εn 6/4 1-εn and the recursive process is stopped when this truncation error is negligible compared with the machine precision.
Within the domain of definition, the function value is itself representable for all representable values of its arguments. However, for values of the arguments near the extremes the above algorithm must be modified so as to avoid causing underflows or overflows in intermediate steps. In extreme regions arguments are prescaled away from the extremes and compensating scaling of the result is done before returning to the calling program.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Carlson B C (1979) Computing elliptic integrals by duplication Numerische Mathematik 33 1–16
Carlson B C (1988) A table of elliptic integrals of the third kind Math. Comput. 51 267–280

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
2:   Y – REAL (KIND=nag_wp)Input
3:   Z – REAL (KIND=nag_wp)Input
On entry: the arguments x, y and z of the function.
Constraint: X, Y, Z≥0.0 and only one of X, Y and Z may be zero.
4:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, one or more of X, Y and Z is negative; the function is undefined.
IFAIL=2
On entry, two or more of X, Y and Z are zero; the function is undefined. On soft failure, the routine returns zero.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

In principle S21BBF is capable of producing full machine precision. However round-off errors in internal arithmetic will result in slight loss of accuracy. This loss should never be excessive as the algorithm does not involve any significant amplification of round-off error. It is reasonable to assume that the result is accurate to within a small multiple of the machine precision.

8 Parallelism and Performance

S21BBF is not threaded in any implementation.

9 Further Comments

You should consult the S Chapter Introduction which shows the relationship of this function to the classical definitions of the elliptic integrals.
If two arguments are equal, the function reduces to the elementary integral RC, computed by S21BAF.

10 Example

This example simply generates a small set of nonextreme arguments which are used with the routine to produce the table of low accuracy results.

10.1 Program Text

Program Text (s21bbfe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (s21bbfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S21BCF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S21BCF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S21BCF returns a value of the symmetrised elliptic integral of the second kind, via the function name.

2 Specification

FUNCTION S21BCF ( X, Y, Z, IFAIL)
REAL (KIND=nag_wp) S21BCF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X, Y, Z

3 Description

S21BCF calculates an approximate value for the integral
RD x,y,z=32∫0∞dt t+xt+y t+z 3
where x, y≥0, at most one of x and y is zero, and z>0.
The basic algorithm, which is due to Carlson (1979) and Carlson (1988), is to reduce the arguments recursively towards their mean by the rule:
x 0 = x,y 0=y,z 0=z μn = xn+yn+3 zn/5 Xn = 1-xn/μn Yn = 1-yn/μn Zn = 1-zn/μn λn = xnyn+ynzn+znxn x n+1 = xn+λn/4 y n+1 = yn+λn/4 z n+1 = zn+λn/4
For n sufficiently large,
εn=max Xn,Yn,Zn∼ 14 n
and the function may be approximated adequately by a fifth order power series
RD x,y,z= 3∑m= 0 n- 1 4-m zm+λn zm + 4-n μn 3 1+ 37 Sn 2 + 13 Sn 3 + 322 Sn 2 2+ 311 Sn 4 + 313 Sn 2 Sn 3 + 313 Sn 5
where Sn m =Xnm+Ynm+3 Znm /2 m. The truncation error in this expansion is bounded by 3 εn 6 1-εn 3 and the recursive process is terminated when this quantity is negligible compared with the machine precision.
The routine may fail either because it has been called with arguments outside the domain of definition, or with arguments so extreme that there is an unavoidable danger of setting underflow or overflow.
Note: RD x,x,x=x-3/2, so there exists a region of extreme arguments for which the function value is not representable.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Carlson B C (1979) Computing elliptic integrals by duplication Numerische Mathematik 33 1–16
Carlson B C (1988) A table of elliptic integrals of the third kind Math. Comput. 51 267–280

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
2:   Y – REAL (KIND=nag_wp)Input
3:   Z – REAL (KIND=nag_wp)Input
On entry: the arguments x, y and z of the function.
Constraint: X, Y≥0.0, Z>0.0 and only one of X and Y may be zero.
4:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, either X or Y is negative, or both X and Y are zero; the function is undefined.
IFAIL=2
On entry, Z≤0.0; the function is undefined.
IFAIL=3
On entry, either Z is too close to zero or both X and Y are too close to zero: there is a danger of setting overflow. See also the Users' Note for your implementation.
IFAIL=4
On entry, at least one of X, Y and Z is too large: there is a danger of setting underflow. On soft failure the routine returns zero. See also the Users' Note for your implementation.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

In principle the routine is capable of producing full machine precision. However round-off errors in internal arithmetic will result in slight loss of accuracy. This loss should never be excessive as the algorithm does not involve any significant amplification of round-off error. It is reasonable to assume that the result is accurate to within a small multiple of the machine precision.

8 Parallelism and Performance

S21BCF is not threaded in any implementation.

9 Further Comments

You should consult the S Chapter Introduction which shows the relationship of this function to the classical definitions of the elliptic integrals.

10 Example

This example simply generates a small set of nonextreme arguments which are used with the routine to produce the table of low accuracy results.

10.1 Program Text

Program Text (s21bcfe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (s21bcfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S21BDF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S21BDF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S21BDF returns a value of the symmetrised elliptic integral of the third kind, via the function name.

2 Specification

FUNCTION S21BDF ( X, Y, Z, R, IFAIL)
REAL (KIND=nag_wp) S21BDF
INTEGER | IFAIL
REAL (KIND=nag_wp) | X, Y, Z, R

3 Description

S21BDF calculates an approximation to the integral
RJ x,y,z,ρ=32∫0∞dt t+ρ t+xt+yt+z
where x, y, z≥0, ρ≠0 and at most one of x, y and z is zero.
If ρ<0, the result computed is the Cauchy principal value of the integral.
The basic algorithm, which is due to Carlson (1979) and Carlson (1988), is to reduce the arguments recursively towards their mean by the rule:
x 0 = x,y 0=y,z 0=z,ρ 0=ρ μn = xn+yn+zn+2 ρn/5 Xn = 1-xn/μn Yn = 1-yn/μn Zn = 1-zn/μn Pn = 1-ρn/μn λn = xnyn+ynzn+znxn x n+1 = xn+λn/4 y n+1 = yn+λn/4 z n+1 = zn+λn/4 ρ n+1 = ρn+λn/4 αn = ρn xn,+yn,+zn+xnynzn 2 βn = ρn ρn+λn 2
For n sufficiently large,
εn=max Xn,Yn,Zn,Pn∼1 4 n
and the function may be approximated by a fifth order power series
RJ x,y,z,ρ= 3∑m= 0 n- 1 4-m RC αm,βm + 4-n μn 3 1+ 37 Sn 2 + 13 Sn 3 + 322 Sn 2 2+ 311 Sn 4 + 313 Sn 2 Sn 3 + 313 Sn 5
where Sn m =Xnm+Ynm+Znm+2 Pnm/2 m.
The truncation error in this expansion is bounded by 3 εn 6/ 1-εn 3 and the recursion process is terminated when this quantity is negligible compared with the machine precision. The routine may fail either because it has been called with arguments outside the domain of definition or with arguments so extreme that there is an unavoidable danger of setting underflow or overflow.
Note: RJ x,x,x,x=x-32, so there exists a region of extreme arguments for which the function value is not representable.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Carlson B C (1979) Computing elliptic integrals by duplication Numerische Mathematik 33 1–16
Carlson B C (1988) A table of elliptic integrals of the third kind Math. Comput. 51 267–280

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
2:   Y – REAL (KIND=nag_wp)Input
3:   Z – REAL (KIND=nag_wp)Input
4:   R – REAL (KIND=nag_wp)Input
On entry: the arguments x, y, z and ρ of the function.
Constraint: X, Y, Z≥0.0, R≠0.0 and at most one of X, Y and Z may be zero.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, at least one of X, Y and Z is negative, or at least two of them are zero; the function is undefined.
IFAIL=2
R=0.0; the function is undefined.
IFAIL=3
On entry, either R is too close to zero, or any two of X, Y and Z are too close to zero; there is a danger of setting overflow. See also the Users' Note for your implementation.
IFAIL=4
On entry, at least one of X, Y, Z and R is too large; there is a danger of setting underflow. See also the Users' Note for your implementation.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

In principle the routine is capable of producing full machine precision. However round-off errors in internal arithmetic will result in slight loss of accuracy. This loss should never be excessive as the algorithm does not involve any significant amplification of round-off error. It is reasonable to assume that the result is accurate to within a small multiple of the machine precision.

8 Parallelism and Performance

S21BDF is not threaded in any implementation.

9 Further Comments

You should consult the S Chapter Introduction which shows the relationship of this function to the classical definitions of the elliptic integrals.
If the argument R is equal to any of the other arguments, the function reduces to the integral RD, computed by S21BCF.

10 Example

This example simply generates a small set of nonextreme arguments which are used with the routine to produce the table of low accuracy results.

10.1 Program Text

Program Text (s21bdfe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (s21bdfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S21BEF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S21BEF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S21BEF returns a value of the classical (Legendre) form of the incomplete elliptic integral of the first kind, via the function name.

2 Specification

FUNCTION S21BEF ( PHI, DM, IFAIL)
REAL (KIND=nag_wp) S21BEF
INTEGER | IFAIL
REAL (KIND=nag_wp) | PHI, DM

3 Description

S21BEF calculates an approximation to the integral
F ϕ∣m = ∫0 ϕ 1-m sin 2⁡θ -12 dθ ,
where 0≤ϕ≤ π 2 , m sin 2⁡ϕ≤1 and m and sin⁡ϕ may not both equal one.
The integral is computed using the symmetrised elliptic integrals of Carlson (Carlson (1979) and Carlson (1988)). The relevant identity is
F ϕ∣m = RF q,r,1 sin⁡ϕ ,
where q=cos 2⁡ϕ , r=1-m sin 2⁡ϕ and RF is the Carlson symmetrised incomplete elliptic integral of the first kind (see S21BBF).

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Carlson B C (1979) Computing elliptic integrals by duplication Numerische Mathematik 33 1–16
Carlson B C (1988) A table of elliptic integrals of the third kind Math. Comput. 51 267–280

5 Arguments

1:   PHI – REAL (KIND=nag_wp)Input
2:   DM – REAL (KIND=nag_wp)Input
On entry: the arguments ϕ and m of the function.
Constraints:
  • 0.0≤PHI≤ π 2;
  • DM× sin 2 PHI ≤1.0 ;
  • Only one of sin PHI and DM may be 1.0.
Note that DM × sin 2 PHI = 1.0 is allowable, as long as DM≠1.0 .
3:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, PHI=value.
Constraint: 0≤PHI≤π 2.
On soft failure, the routine returns zero.
IFAIL=2
On entry, PHI=value and DM=value; the integral is undefined.
Constraint: DM×sin 2 PHI≤1.0.
On soft failure, the routine returns zero.
IFAIL=3
On entry, sin PHI=1 and DM=1.0; the integral is infinite.
On soft failure, the routine returns the largest machine number (see X02ALF).
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

In principle S21BEF is capable of producing full machine precision. However round-off errors in internal arithmetic will result in slight loss of accuracy. This loss should never be excessive as the algorithm does not involve any significant amplification of round-off error. It is reasonable to assume that the result is accurate to within a small multiple of the machine precision.

8 Parallelism and Performance

S21BEF is not threaded in any implementation.

9 Further Comments

You should consult the S Chapter Introduction, which shows the relationship between this routine and the Carlson definitions of the elliptic integrals. In particular, the relationship between the argument-constraints for both forms becomes clear.
For more information on the algorithm used to compute RF , see the routine document for S21BBF.
If you wish to input a value of PHI outside the range allowed by this routine you should refer to Section 17.4 of Abramowitz and Stegun (1972) for useful identities. For example, F-ϕ|m=-F ϕ|m and F sπ±ϕ|m=2 sK m±F ϕ|m where s is an integer and K m is the complete elliptic integral given by S21BHF.
A parameter m>1 can be replaced by one less than unity using F ϕ|m=1 m F θ|1 m, sin⁡θ=m sin⁡ϕ.

10 Example

This example simply generates a small set of nonextreme arguments that are used with the routine to produce the table of results.

10.1 Program Text

Program Text (s21befe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (s21befe.r)

GnuplotProduced by GNUPLOT 4.6 patchlevel 3 0.8 0.9 1 1.1 1.2 1.3 1.4 1.5 1.6 0.55 0.6 0.65 0.7 0.75 0.8 0.85 0.9 0.95 1 0 2 4 6 8 10 Example Program Classical (Legendre) Form of the Incomplete Elliptic Integral of the First Kind gnuplot_plot_1 f m
S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S21BFF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S21BFF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S21BFF returns a value of the classical (Legendre) form of the incomplete elliptic integral of the second kind, via the function name.

2 Specification

FUNCTION S21BFF ( PHI, DM, IFAIL)
REAL (KIND=nag_wp) S21BFF
INTEGER | IFAIL
REAL (KIND=nag_wp) | PHI, DM

3 Description

S21BFF calculates an approximation to the integral
E ϕ∣m = ∫0 ϕ 1-m sin 2⁡θ 12 dθ ,
where 0≤ϕ≤ π 2 and m sin 2⁡ϕ≤1 .
The integral is computed using the symmetrised elliptic integrals of Carlson (Carlson (1979) and Carlson (1988)). The relevant identity is
E ϕ∣m = sin⁡ϕ RF q,r,1 - 13 m sin 3⁡ϕ RD q,r,1 ,
where q=cos 2⁡ϕ , r=1-m sin 2⁡ϕ , RF is the Carlson symmetrised incomplete elliptic integral of the first kind (see S21BBF) and RD is the Carlson symmetrised incomplete elliptic integral of the second kind (see S21BCF).

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Carlson B C (1979) Computing elliptic integrals by duplication Numerische Mathematik 33 1–16
Carlson B C (1988) A table of elliptic integrals of the third kind Math. Comput. 51 267–280

5 Arguments

1:   PHI – REAL (KIND=nag_wp)Input
2:   DM – REAL (KIND=nag_wp)Input
On entry: the arguments ϕ and m of the function.
Constraints:
  • 0.0≤PHI≤ π 2;
  • DM× sin 2 PHI ≤1.0 .
3:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, PHI=value.
Constraint: 0≤PHI≤π 2.
IFAIL=2
On entry, PHI=value and DM=value; the integral is undefined.
Constraint: DM×sin 2 PHI≤1.0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

In principle S21BFF is capable of producing full machine precision. However round-off errors in internal arithmetic will result in slight loss of accuracy. This loss should never be excessive as the algorithm does not involve any significant amplification of round-off error. It is reasonable to assume that the result is accurate to within a small multiple of the machine precision.

8 Parallelism and Performance

S21BFF is not threaded in any implementation.

9 Further Comments

You should consult the S Chapter Introduction, which shows the relationship between this routine and the Carlson definitions of the elliptic integrals. In particular, the relationship between the argument-constraints for both forms becomes clear.
For more information on the algorithms used to compute RF and RD , see the routine documents for S21BBF and S21BCF, respectively.
If you wish to input a value of PHI outside the range allowed by this routine you should refer to Section 17.4 of Abramowitz and Stegun (1972) for useful identities. For example, E-ϕ|m=-E ϕ|m. A parameter m>1 can be replaced by one less than unity using E ϕ|m=m E ϕ⁢m|1 m-m-1 ϕ.

10 Example

This example simply generates a small set of nonextreme arguments that are used with the routine to produce the table of results.

10.1 Program Text

Program Text (s21bffe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (s21bffe.r)

GnuplotProduced by GNUPLOT 4.6 patchlevel 3 1 1.1 1.2 1.3 1.4 1.5 1.6 0.55 0.6 0.65 0.7 0.75 0.8 0.85 0.9 0.95 1 0.8 0.9 1 1.1 1.2 1.3 Example Program Classical (Legendre) Form of the Incomplete Elliptic Integral of the Second Kind gnuplot_plot_1 f m
S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S21BGF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S21BGF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S21BGF returns a value of the classical (Legendre) form of the incomplete elliptic integral of the third kind, via the function name.

2 Specification

FUNCTION S21BGF ( DN, PHI, DM, IFAIL)
REAL (KIND=nag_wp) S21BGF
INTEGER | IFAIL
REAL (KIND=nag_wp) | DN, PHI, DM

3 Description

S21BGF calculates an approximation to the integral
Π n;ϕ∣m = ∫0 ϕ 1-n sin 2⁡θ -1 1-m sin 2⁡θ -12 dθ ,
where 0≤ϕ≤ π 2 , m sin 2⁡ϕ≤1 , m and sin⁡ϕ may not both equal one, and n sin 2⁡ϕ≠1 .
The integral is computed using the symmetrised elliptic integrals of Carlson (Carlson (1979) and Carlson (1988)). The relevant identity is
Π n;ϕ∣m = sin⁡ϕ RF q,r,1 + 13 n sin 3⁡ϕ RJ q,r,1,s ,
where q=cos 2⁡ϕ , r=1-m sin 2⁡ϕ , s=1-n sin 2⁡ϕ , RF is the Carlson symmetrised incomplete elliptic integral of the first kind (see S21BBF) and RJ is the Carlson symmetrised incomplete elliptic integral of the third kind (see S21BDF).

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Carlson B C (1979) Computing elliptic integrals by duplication Numerische Mathematik 33 1–16
Carlson B C (1988) A table of elliptic integrals of the third kind Math. Comput. 51 267–280

5 Arguments

1:   DN – REAL (KIND=nag_wp)Input
2:   PHI – REAL (KIND=nag_wp)Input
3:   DM – REAL (KIND=nag_wp)Input
On entry: the arguments n, ϕ and m of the function.
Constraints:
  • 0.0≤PHI≤ π 2;
  • DM× sin 2 PHI ≤1.0 ;
  • Only one of sin PHI and DM may be 1.0;
  • DN× sin 2 PHI ≠ 1.0 .
Note that DM × sin 2 PHI = 1.0 is allowable, as long as DM≠1.0 .
4:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, PHI=value.
Constraint: 0≤PHI≤π/2.
IFAIL=2
On entry, PHI=value and DM=value; the integral is undefined.
Constraint: DM×sin 2 PHI≤1.0.
IFAIL=3
On entry, sin PHI=1 and DM=1.0; the integral is infinite.
IFAIL=4
On entry, PHI=value and DN=value; the integral is infinite.
Constraint: DN×sin 2 PHI≠1.0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

In principle S21BGF is capable of producing full machine precision. However round-off errors in internal arithmetic will result in slight loss of accuracy. This loss should never be excessive as the algorithm does not involve any significant amplification of round-off error. It is reasonable to assume that the result is accurate to within a small multiple of the machine precision.

8 Parallelism and Performance

S21BGF is not threaded in any implementation.

9 Further Comments

You should consult the S Chapter Introduction, which shows the relationship between this routine and the Carlson definitions of the elliptic integrals. In particular, the relationship between the argument-constraints for both forms becomes clear.
For more information on the algorithms used to compute RF and RJ , see the routine documents for S21BBF and S21BDF, respectively.
If you wish to input a value of PHI outside the range allowed by this routine you should refer to Section 17.4 of Abramowitz and Stegun (1972) for useful identities.

10 Example

This example simply generates a small set of nonextreme arguments that are used with the routine to produce the table of results.

10.1 Program Text

Program Text (s21bgfe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (s21bgfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S21BHF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S21BHF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S21BHF returns a value of the classical (Legendre) form of the complete elliptic integral of the first kind, via the function name.

2 Specification

FUNCTION S21BHF ( DM, IFAIL)
REAL (KIND=nag_wp) S21BHF
INTEGER | IFAIL
REAL (KIND=nag_wp) | DM

3 Description

S21BHF calculates an approximation to the integral
K m = ∫0 π 2 1-m sin 2⁡θ -12 dθ ,
where m<1 .
The integral is computed using the symmetrised elliptic integrals of Carlson (Carlson (1979) and Carlson (1988)). The relevant identity is
K m = RF 0,1-m,1 ,
where RF is the Carlson symmetrised incomplete elliptic integral of the first kind (see S21BBF).

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Carlson B C (1979) Computing elliptic integrals by duplication Numerische Mathematik 33 1–16
Carlson B C (1988) A table of elliptic integrals of the third kind Math. Comput. 51 267–280

5 Arguments

1:   DM – REAL (KIND=nag_wp)Input
On entry: the argument m of the function.
Constraint: DM<1.0.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, DM=value; the integral is undefined.
Constraint: DM<1.0.
On soft failure, the routine returns zero.
IFAIL=2
On entry, DM=1.0; the integral is infinite.
On soft failure, the routine returns the largest machine number (see X02ALF).
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

In principle S21BHF is capable of producing full machine precision. However round-off errors in internal arithmetic will result in slight loss of accuracy. This loss should never be excessive as the algorithm does not involve any significant amplification of round-off error. It is reasonable to assume that the result is accurate to within a small multiple of the machine precision.

8 Parallelism and Performance

S21BHF is not threaded in any implementation.

9 Further Comments

You should consult the S Chapter Introduction, which shows the relationship between this routine and the Carlson definitions of the elliptic integrals. In particular, the relationship between the argument-constraints for both forms becomes clear.
For more information on the algorithm used to compute RF , see the routine document for S21BBF.

10 Example

This example simply generates a small set of nonextreme arguments that are used with the routine to produce the table of results.

10.1 Program Text

Program Text (s21bhfe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (s21bhfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S21BJF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S21BJF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S21BJF returns a value of the classical (Legendre) form of the complete elliptic integral of the second kind, via the function name.

2 Specification

FUNCTION S21BJF ( DM, IFAIL)
REAL (KIND=nag_wp) S21BJF
INTEGER | IFAIL
REAL (KIND=nag_wp) | DM

3 Description

S21BJF calculates an approximation to the integral
E m = ∫0 π 2 1-m sin 2⁡θ 12 dθ ,
where m≤1 .
The integral is computed using the symmetrised elliptic integrals of Carlson (Carlson (1979) and Carlson (1988)). The relevant identity is
E m = RF 0,1-m,1 - 13 m RD 0,1-m,1 ,
where RF is the Carlson symmetrised incomplete elliptic integral of the first kind (see S21BBF) and RD is the Carlson symmetrised incomplete elliptic integral of the second kind (see S21BCF).

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Carlson B C (1979) Computing elliptic integrals by duplication Numerische Mathematik 33 1–16
Carlson B C (1988) A table of elliptic integrals of the third kind Math. Comput. 51 267–280

5 Arguments

1:   DM – REAL (KIND=nag_wp)Input
On entry: the argument m of the function.
Constraint: DM≤1.0.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, DM=value; the integral is undefined.
Constraint: DM≤1.0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

In principle S21BJF is capable of producing full machine precision. However round-off errors in internal arithmetic will result in slight loss of accuracy. This loss should never be excessive as the algorithm does not involve any significant amplification of round-off error. It is reasonable to assume that the result is accurate to within a small multiple of the machine precision.

8 Parallelism and Performance

S21BJF is not threaded in any implementation.

9 Further Comments

You should consult the S Chapter Introduction, which shows the relationship between this routine and the Carlson definitions of the elliptic integrals. In particular, the relationship between the argument-constraints for both forms becomes clear.
For more information on the algorithms used to compute RF and RD , see the routine documents for S21BBF and S21BCF, respectively.

10 Example

This example simply generates a small set of nonextreme arguments that are used with the routine to produce the table of results.

10.1 Program Text

Program Text (s21bjfe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (s21bjfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S21CAF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S21CAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S21CAF evaluates the Jacobian elliptic functions sn, cn and dn.

2 Specification

SUBROUTINE S21CAF ( U, M, SN, CN, DN, IFAIL)
INTEGER | IFAIL
REAL (KIND=nag_wp) | U, M, SN, CN, DN

3 Description

S21CAF evaluates the Jacobian elliptic functions of argument u and argument m,
sn u∣m = sin⁡ϕ, cn u∣m = cos⁡ϕ, dn u∣m = 1-m sin 2⁡ϕ,
where ϕ, called the amplitude of u, is defined by the integral
u=∫0 ϕ dθ 1-m sin 2⁡θ .
The elliptic functions are sometimes written simply as sn⁡u, cn⁡u and dn⁡u, avoiding explicit reference to the argument m.
Another nine elliptic functions may be computed via the formulae
cd⁡u = cn⁡u/dn⁡u sd⁡u = sn⁡u/dn⁡u nd⁡u = 1/dn⁡u dc⁡u = dn⁡u/cn⁡u nc⁡u = 1/cn⁡u sc⁡u = sn⁡u/cn⁡u ns⁡u = 1/sn⁡u ds⁡u = dn⁡u/sn⁡u cs⁡u = cn⁡u/sn⁡u
(see Abramowitz and Stegun (1972)).
S21CAF is based on a procedure given by Bulirsch (1960), and uses the process of the arithmetic-geometric mean (16.9 in Abramowitz and Stegun (1972)). Constraints are placed on the values of u and m in order to avoid the possibility of machine overflow.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Bulirsch R (1960) Numerical calculation of elliptic integrals and elliptic functions Numer. Math. 7 76–90

5 Arguments

1:   U – REAL (KIND=nag_wp)Input
2:   M – REAL (KIND=nag_wp)Input
On entry: the argument u and the argument m of the functions, respectively.
Constraints:
  • abs U ≤ λ , where λ = 1 / X02AMF;
  • if abs U < 1 / λ , abs M ≤ λ .
3:   SN – REAL (KIND=nag_wp)Output
4:   CN – REAL (KIND=nag_wp)Output
5:   DN – REAL (KIND=nag_wp)Output
On exit: the values of the functions sn⁡u, cn⁡u and dn⁡u, respectively.
6:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, abs U>λ, where λ=1/X02AMF.
IFAIL=2
On entry, abs M>λ and abs U<1/λ.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

In principle the routine is capable of achieving full relative precision in the computed values. However, the accuracy obtainable in practice depends on the accuracy of the standard elementary functions such as SIN and COS.

8 Parallelism and Performance

S21CAF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads values of the argument u and argument m from a file, evaluates the function and prints the results.

10.1 Program Text

Program Text (s21cafe.f90)

10.2 Program Data

Program Data (s21cafe.d)

10.3 Program Results

Program Results (s21cafe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S21CBF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S21CBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S21CBF evaluates the Jacobian elliptic functions sn⁡z, cn⁡z and dn⁡z for a complex argument z.

2 Specification

SUBROUTINE S21CBF ( Z, AK2, SN, CN, DN, IFAIL)
INTEGER | IFAIL
REAL (KIND=nag_wp) | AK2
COMPLEX (KIND=nag_wp) | Z, SN, CN, DN

3 Description

S21CBF evaluates the Jacobian elliptic functions sn z∣k, cn z∣k and dn z∣k given by
sn z∣k = sin⁡ϕ cn z∣k = cos⁡ϕ dn z∣k = 1-k 2 sin 2⁡ϕ,
where z is a complex argument, k is a real argument (the modulus) with k 2≤1 and ϕ (the amplitude of z) is defined by the integral
z=∫0 ϕ dθ 1-k 2 sin 2⁡θ .
The above definitions can be extended for values of k 2>1 (see Salzer (1962)) by means of the formulae
sn z∣k = k 1 sn kz∣k 1 cn z∣k = dn kz∣k 1 dn z∣k = cn kz∣k 1,
where k 1=1/k.
Special values include
sn z∣0 = sin⁡z cn z∣0 = cos⁡z dn z∣0 = 1 sn z∣1 = tanh⁡z cn z∣1 = sech⁡z dn z∣1 = sech⁡z.
These functions are often simply written as sn⁡z, cn⁡z and dn⁡z, thereby avoiding explicit reference to the argument k. They can also be expressed in terms of Jacobian theta functions (see S21CCF).
Another nine elliptic functions may be computed via the formulae
cd⁡z = cn⁡z/dn⁡z sd⁡z = sn⁡z/dn⁡z nd⁡z = 1/dn⁡z dc⁡z = dn⁡z/cn⁡z nc⁡z = 1/cn⁡z sc⁡z = sn⁡z/cn⁡z ns⁡z = 1/sn⁡z ds⁡z = dn⁡z/sn⁡z cs⁡z = cn⁡z/sn⁡z
(see Abramowitz and Stegun (1972)).
The values of sn⁡z, cn⁡z and dn⁡z are obtained by calls to S21CAF. Further details can be found in Section 9.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Salzer H E (1962) Quick calculation of Jacobian elliptic functions Comm. ACM 5 399

5 Arguments

1:   Z – COMPLEX (KIND=nag_wp)Input
On entry: the argument z of the functions.
Constraints:
  • abs Re(Z)≤=λ;
  • abs Im(Z)≤λ, where λ=1/X02AMF.
2:   AK2 – REAL (KIND=nag_wp)Input
On entry: the value of k 2.
Constraint: 0.0≤AK2≤1.0.
3:   SN – COMPLEX (KIND=nag_wp)Output
4:   CN – COMPLEX (KIND=nag_wp)Output
5:   DN – COMPLEX (KIND=nag_wp)Output
On exit: the values of the functions sn⁡z, cn⁡z and dn⁡z, respectively.
6:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | AK2<0.0,
or | AK2>1.0,
or | abs Re Z>λ,
or | abs Im Z>λ, where λ=1/X02AMF.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

In principle the routine is capable of achieving full relative precision in the computed values. However, the accuracy obtainable in practice depends on the accuracy of the standard elementary functions such as SIN and COS.

8 Parallelism and Performance

S21CBF is not threaded in any implementation.

9 Further Comments

The values of sn⁡z, cn⁡z and dn⁡z are computed via the formulae
sn⁡z = sn u,kdn v,k′ 1-dn 2 u,ksn 2 v,k′ + i cn u,kdn u,ksn v,k′cn v,k′ 1-dn 2 u,ksn 2 v,k′ cn⁡z = cn u,kcn v,k′ 1-dn 2 u,ksn 2 v,k′ - i sn u,kdn u,ksn v,k′dn v,k′ 1-dn 2 u,ksn 2 v,k′ dn⁡z = dn u,kcn v,k′dn v,k′ 1-dn 2 u,ksn 2 v,k′ - i k 2 sn u,kcn u,ksn v,k′ 1-dn 2 u,ksn 2 v,k′ ,
where z=u+iv and k′=1-k 2 (the complementary modulus).

10 Example

This example evaluates sn⁡z, cn⁡z and dn⁡z at z=-2.0+3.0 i when k=0.5, and prints the results.

10.1 Program Text

Program Text (s21cbfe.f90)

10.2 Program Data

Program Data (s21cbfe.d)

10.3 Program Results

Program Results (s21cbfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S21CCF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S21CCF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S21CCF returns the value of one of the Jacobian theta functions θ 0 x,q, θ 1 x,q, θ 2 x,q, θ 3 x,q or θ 4 x,q for a real argument x and non-negative q<1, via the function name.

2 Specification

FUNCTION S21CCF ( K, X, Q, IFAIL)
REAL (KIND=nag_wp) S21CCF
INTEGER | K, IFAIL
REAL (KIND=nag_wp) | X, Q

3 Description

S21CCF evaluates an approximation to the Jacobian theta functions θ 0 x,q, θ 1 x,q, θ 2 x,q, θ 3 x,q and θ 4 x,q given by
θ 0 x,q = 1+2∑n=1∞-1 nq n 2 cos 2 nπx, θ 1 x,q = 2∑n=0∞-1 nq n+12 2 sin 2 n+1 πx, θ 2 x,q = 2∑n=0∞q n+12 2 cos 2 n+1 πx, θ 3 x,q = 1+2∑n=1∞q n 2 cos 2 nπx, θ 4 x,q = θ 0 x,q,
where x and q (the nome) are real with 0≤q<1.
These functions are important in practice because every one of the Jacobian elliptic functions (see S21CBF) can be expressed as the ratio of two Jacobian theta functions (see Whittaker and Watson (1990)). There is also a bewildering variety of notations used in the literature to define them. Some authors (e.g., Section 16.27 of Abramowitz and Stegun (1972)) define the argument in the trigonometric terms to be x instead of πx. This can often lead to confusion, so great care must therefore be exercised when consulting the literature. Further details (including various relations and identities) can be found in the references.
S21CCF is based on a truncated series approach. If t differs from x or -x by an integer when 0≤t≤12 , it follows from the periodicity and symmetry properties of the functions that θ 1 x,q=±θ 1 t,q and θ 3 x,q=±θ 3 t,q. In a region for which the approximation is sufficiently accurate, θ 1 is set equal to the first term (n=0) of the transformed series
θ 1 t,q=2 λπ e-λ t 2∑n=0∞-1 ne-λ n+12 2 sinh 2 n+1 λt
and θ 3 is set equal to the first two terms (i.e., n≤1) of
θ 3 t,q=λπ e-λ t 2 1+2∑n=1∞e-λ n 2 cosh 2 nλt ,
where λ= π 2/ loge⁡q . Otherwise, the trigonometric series for θ 1 t,q and θ 3 t,q are used. For all values of x, θ 0 and θ 2 are computed from the relations θ 0 x,q=θ 3 12-x,q and θ 2 x,q=θ 1 12-x,q.

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Byrd P F and Friedman M D (1971) Handbook of Elliptic Integrals for Engineers and Scientists pp. 315–320 (2nd Edition) Springer–Verlag
Magnus W, Oberhettinger F and Soni R P (1966) Formulas and Theorems for the Special Functions of Mathematical Physics 371–377 Springer–Verlag
Tølke F (1966) Praktische Funktionenlehre (Bd. II) 1–38 Springer–Verlag
Whittaker E T and Watson G N (1990) A Course in Modern Analysis (4th Edition) Cambridge University Press

5 Arguments

1:   K – INTEGERInput
On entry: denotes the function θk x,q to be evaluated. Note that K=4 is equivalent to K=0.
Constraint: 0≤K≤4.
2:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
3:   Q – REAL (KIND=nag_wp)Input
On entry: the argument q of the function.
Constraint: 0.0≤Q<1.0.
4:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | K<0,
or | K>4,
or | Q<0.0,
or | Q≥1.0,
IFAIL=2
The evaluation has been abandoned because the function value is infinite. The result is returned as the largest machine representable number (see X02ALF).
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

In principle the routine is capable of achieving full relative precision in the computed values. However, the accuracy obtainable in practice depends on the accuracy of the standard elementary functions such as sin and cos.

8 Parallelism and Performance

S21CCF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example evaluates θ 2 x,q at x=0.7 when q=0.4, and prints the results.

10.1 Program Text

Program Text (s21ccfe.f90)

10.2 Program Data

Program Data (s21ccfe.d)

10.3 Program Results

Program Results (s21ccfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S21DAF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S21DAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S21DAF returns the value of the general elliptic integral of the second kind F z,k′,a,b for a complex argument z, via the function name.

2 Specification

FUNCTION S21DAF ( Z, AKP, A, B, IFAIL)
COMPLEX (KIND=nag_wp) S21DAF
INTEGER | IFAIL
REAL (KIND=nag_wp) | AKP, A, B
COMPLEX (KIND=nag_wp) | Z

3 Description

S21DAF evaluates an approximation to the general elliptic integral of the second kind F z,k′,a,b given by
F z,k′,a,b=∫0 z a+b ζ 2 1+ζ 2 1+ζ 21+k′2ζ 2 dζ,
where a and b are real arguments, z is a complex argument whose real part is non-negative and k′ is a real argument (the complementary modulus). The evaluation of F is based on the Gauss transformation. Further details, in particular for the conformal mapping provided by F, can be found in Bulirsch (1960).
Special values include
F z, k ′ ,1,1 = ∫ 0 z d ζ 1 + ζ 2 1 + k′ 2 ζ 2 ,
or F 1 z,k′ (the elliptic integral of the first kind) and
F z,k′,1,k′2=∫0 z 1+k′2ζ 2 1+ζ 2 1+ζ 2 dζ,
or F 2 z,k′ (the elliptic integral of the second kind). Note that the values of F 1 z,k′ and F 2 z,k′ are equal to tan-1 z in the trivial case k′=1.
S21DAF is derived from an Algol 60 procedure given by Bulirsch (1960). Constraints are placed on the values of z and k′ in order to avoid the possibility of machine overflow.

4 References

Bulirsch R (1960) Numerical calculation of elliptic integrals and elliptic functions Numer. Math. 7 76–90

5 Arguments

1:   Z – COMPLEX (KIND=nag_wp)Input
On entry: the argument z of the function.
Constraints:
  • 0.0≤Re(Z)≤λ;
  • abs Im(Z)≤λ, where λ 6=1/X02AMF.
2:   AKP – REAL (KIND=nag_wp)Input
On entry: the argument k′ of the function.
Constraint: abs AKP ≤ λ .
3:   A – REAL (KIND=nag_wp)Input
On entry: the argument a of the function.
4:   B – REAL (KIND=nag_wp)Input
On entry: the argument b of the function.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | Re Z<0.0,
or | Re Z>λ,
or | Im Z>λ,
or | AKP>λ, where λ 6=1/X02AMF.
IFAIL=2
The iterative procedure used to evaluate the integral has failed to converge. The result is returned as zero.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

In principle the routine is capable of achieving full relative precision in the computed values. However, the accuracy obtainable in practice depends on the accuracy of the standard elementary functions such as atan2 and log.

8 Parallelism and Performance

S21DAF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example evaluates the elliptic integral of the first kind F 1 z,k′ given by
F 1 z,k′=∫0 z dζ 1+ζ 21+k′2ζ 2 ,
where z=1.2+3.7 i and k′=0.5, and prints the results.

10.1 Program Text

Program Text (s21dafe.f90)

10.2 Program Data

Program Data (s21dafe.d)

10.3 Program Results

Program Results (s21dafe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S22AAF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S22AAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S22AAF returns a sequence of values for either the unnormalized or normalized Legendre functions of the first kind Pnm x or Pnm¯x for real x of a given order m and degree n=0,1,…,N.

2 Specification

SUBROUTINE S22AAF ( MODE, X, M, NL, P, IFAIL)
INTEGER | MODE, M, NL, IFAIL
REAL (KIND=nag_wp) | X, P(0:NL)

3 Description

S22AAF evaluates a sequence of values for either the unnormalized or normalized Legendre (m=0) or associated Legendre (m≠0) functions of the first kind Pnm x or Pnm¯x, where x is real with -1≤x≤1, of order m and degree n=0,1,…,N defined by
Pnm x = 1-x 2 m/2 dm d xm Pn x   if ​m≥0, Pnm x = n+m! n-m! Pn-m x   if ​m<0  and Pnm¯x = 2 n+1 2 n-m! n+m! Pnm x
respectively; Pn x is the (unassociated) Legendre polynomial of degree n given by
Pn x≡Pn 0 x=1 2 n n! dn d xn x 2-1 n
(the Rodrigues formula). Note that some authors (e.g., Abramowitz and Stegun (1972)) include an additional factor of -1 m (the Condon–Shortley Phase) in the definitions of Pnm x and Pnm¯x. They use the notation P mn x≡-1 m Pnm x in order to distinguish between the two cases.
S22AAF is based on a standard recurrence relation described in Section 8.5.3 of Abramowitz and Stegun (1972). Constraints are placed on the values of m and n in order to avoid the possibility of machine overflow. It also sets the appropriate elements of the array P (see Section 5) to zero whenever the required function is not defined for certain values of m and n (e.g., m=-5 and n=3).

4 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

5 Arguments

1:   MODE – INTEGERInput
On entry: indicates whether the sequence of function values is to be returned unnormalized or normalized.
MODE=1
The sequence of function values is returned unnormalized.
MODE=2
The sequence of function values is returned normalized.
Constraint: MODE=1 or 2.
2:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
Constraint: abs X≤1.0.
3:   M – INTEGERInput
On entry: the order m of the function.
Constraint: abs M ≤ 27 .
4:   NL – INTEGERInput
On entry: the degree N of the last function required in the sequence.
Constraints:
  • NL≥0;
  • if M=0, NL≤100;
  • if M≠0, NL ≤ 55 - abs M .
5:   P 0:NL – REAL (KIND=nag_wp) arrayOutput
On exit: the required sequence of function values as follows:
  • if MODE=1, P n contains Pnm x , for n=0,1,…,N;
  • if MODE=2, P n contains Pnm ¯ x , for n=0,1,…,N.
6:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | abs X>1.0,
or | MODE≠1 or 2,
or | NL<0,
or | NL>100 when M=0,
or | abs M>27,
or | NL+abs M>55 when M≠0.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The computed function values should be accurate to within a small multiple of the machine precision except when underflow (or overflow) occurs, in which case the true function values are within a small multiple of the underflow (or overflow) threshold of the machine.

8 Parallelism and Performance

S22AAF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example reads the values of the arguments x, m and N from a file, calculates the sequence of unnormalized associated Legendre function values Pnm x,P n+1 m x,…,P n+N m x, and prints the results.

10.1 Program Text

Program Text (s22aafe.f90)

10.2 Program Data

Program Data (s22aafe.d)

10.3 Program Results

Program Results (s22aafe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S22BAF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S22BAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S22BAF returns a value for the confluent hypergeometric function F 1 1 a;b;x with real parameters a and b, and real argument x. This function is sometimes also known as Kummer's function M a,b,x.

2 Specification

SUBROUTINE S22BAF ( A, B, X, M, IFAIL)
INTEGER | IFAIL
REAL (KIND=nag_wp) | A, B, X, M

3 Description

S22BAF returns a value for the confluent hypergeometric function F 1 1 a;b;x with real parameters a and b, and real argument x. This function is unbounded or not uniquely defined for b equal to zero or a negative integer.
The associated routine S22BBF performs the same operations, but returns M in the scaled form M=mf×2 ms to allow calculations to be performed when M is not representable as a single working precision number. It also accepts the parameters a and b as summations of an integer and a decimal fraction, giving higher accuracy when a or b are close to an integer. In such cases, S22BBF should be used when high accuracy is required.
The confluent hypergeometric function is defined by the confluent series
F 1 1 a;b;x = M a,b,x = ∑ s=0 ∞ a s xs b s s! = 1 + a b x + a a+1 b b+1 2! x 2 + ⋯
where a s = 1 a a+1 a+2 … a+s-1 is the rising factorial of a. M a,b,x is a solution to the second order ODE (Kummer's Equation):
x d 2 M d x 2 + b-x dM dx - a M = 0 . (1)
Given the parameters and argument a,b,x , this routine determines a set of safe values αi,βi,ζi ∣ i≤2 and selects an appropriate algorithm to accurately evaluate the functions Mi αi,βi,ζi . The result is then used to construct the solution to the original problem M a,b,x using, where necessary, recurrence relations and/or continuation.
Additionally, an artificial bound, arbnd is placed on the magnitudes of a, b and x to minimize the occurrence of overflow in internal calculations. arbnd = 0.0001 × Imax , where Imax=X02BBF. It should, however, not be assumed that this routine will produce an accurate result for all values of a, b and x satisfying this criterion.
Please consult the NIST Digital Library of Mathematical Functions or the companion (2010) for a detailed discussion of the confluent hypergeoemtric function including special cases, transformations, relations and asymptotic approximations.

4 References

NIST Handbook of Mathematical Functions (2010) (eds F W J Olver, D W Lozier, R F Boisvert, C W Clark) Cambridge University Press
Pearson J (2009) Computation of hypergeometric functions MSc Dissertation, Mathematical Institute, University of Oxford

5 Arguments

1:   A – REAL (KIND=nag_wp)Input
On entry: the parameter a of the function.
Constraint: A≤arbnd.
2:   B – REAL (KIND=nag_wp)Input
On entry: the parameter b of the function.
Constraint: B≤arbnd.
3:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
Constraint: X≤arbnd.
4:   M – REAL (KIND=nag_wp)Output
On exit: the solution M a,b,x.
Note: if overflow occurs upon completion, as indicated by IFAIL=2, M a,b,x may be assumed to be too large to be representable. M will be returned as ±Rmax, where Rmax is the largest representable real number (see X02ALF). The sign of M should match the sign of M a,b,x. If overflow occurs during a subcalculation, as indicated by IFAIL=5, the sign may be incorrect, and the true value of M a,b,x may or may not be greater than Rmax. In either case it is advisable to subsequently use S22BBF.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
Underflow occurred during the evaluation of M a,b,x.
The returned value may be inaccurate.
IFAIL=2
On completion, overflow occurred in the evaluation of M a,b,x.
IFAIL=3
All approximations have completed, and the final residual estimate indicates some precision may have been lost.
Relative residual =value.
IFAIL=4
All approximations have completed, and the final residual estimate indicates no accuracy can be guaranteed.
Relative residual =value.
IFAIL=5
Overflow occurred in a subcalculation of M a,b,x.
The answer may be completely incorrect.
IFAIL=11
On entry, A=value.
Constraint: A≤arbnd=value.
IFAIL=31
On entry, B=value.
Constraint: B≤arbnd=value.
IFAIL=32
On entry, B=value.
M a,b,x is undefined when b is zero or a negative integer.
IFAIL=51
On entry, X=value.
Constraint: X≤arbnd=value.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

In general, if IFAIL=0, the value of M may be assumed accurate, with the possible loss of one or two decimal places. Assuming the result does not under or overflow, an error estimate res is made internally using equation (1). If the magnitude of res is sufficiently large, a nonzero IFAIL will be returned. Specifically,
IFAIL=0 | res≤1000 ε
IFAIL=3 | 1000 ε<res≤0.1
IFAIL=4 | res>0.1
where ε is the machine precision as returned by X02AJF.
A further estimate of the residual can be constructed using equation (1), and the differential identity,
d M a,b,x dx = ab M a+1,b+1,x , d 2 M a,b,x d x 2 = a a+1 b b+1 M a+2,b+2,x .
This estimate is however dependent upon the error involved in approximating M a+1,b+1,x and M a+2,b+2,x .
Furthermore, the accuracy of the solution, and the error estimate, can be dependent upon the accuracy of the decimal fraction of the input parameters a and b. For example, if b=bi+br=100+1.0E−6, then on a machine with 16 decimal digits of precision, the internal calculation of br will only be accurate to 8 decimal places. This can subsequently pollute the final solution by several decimal places without affecting the residual estimate as greatly. Should you require higher accuracy in such regions, then you should use S22BBF, which requires you to supply the correct decimal fraction.

8 Parallelism and Performance

S22BAF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
S22BAF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

None.

10 Example

This example prints the results returned by S22BAF called using parameters a=13.6 and b=14.2 with 11 differing values of argument x.

10.1 Program Text

Program Text (s22bafe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (s22bafe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S22BBF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S22BBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S22BBF returns a value for the confluent hypergeometric function F 1 1 a;b;x , with real parameters a and b and real argument x. The solution is returned in the scaled form F 1 1 a;b;x = mf × 2 ms . This function is sometimes also known as Kummer's function M a,b,x.

2 Specification

SUBROUTINE S22BBF ( ANI, ADR, BNI, BDR, X, FRM, SCM, IFAIL)
INTEGER | SCM, IFAIL
REAL (KIND=nag_wp) | ANI, ADR, BNI, BDR, X, FRM

3 Description

S22BBF returns a value for the confluent hypergeometric function F 1 1 a;b;x , with real parameters a and b and real argument x, in the scaled form F 1 1 a;b;x = mf × 2 ms , where mf is the real scaled component and ms is the integer power of two scaling. This function is unbounded or not uniquely defined for b equal to zero or a negative integer.
The confluent hypergeometric function is defined by the confluent series,
F 1 1 a;b;x = M a,b,x = ∑ s=0 ∞ a s xs b s s! = 1 + a b x + a a+1 b b+1 2! x 2 + ⋯
where a s = 1 a a+1 a+2 … a+s-1 is the rising factorial of a . M a,b,x is a solution to the second order ODE (Kummer's Equation):
x d 2 M d x 2 + b-x dM dx - a M = 0 . (1)
Given the parameters and argument a,b,x , this routine determines a set of safe values αi,βi,ζi ∣ i≤2 and selects an appropriate algorithm to accurately evaluate the functions Mi αi,βi,ζi . The result is then used to construct the solution to the original problem M a,b,x using, where necessary, recurrence relations and/or continuation.
For improved precision in the final result, this routine accepts a and b split into an integral and a decimal fractional component. Specifically a=ai+ar, where ar≤0.5 and ai=a-ar is integral. b is similarly deconstructed.
Additionally, an artificial bound, arbnd is placed on the magnitudes of ai, bi and x to minimize the occurrence of overflow in internal calculations. arbnd = 0.0001 × Imax , where Imax=X02BBF. It should, however, not be assumed that this routine will produce an accurate result for all values of ai, bi and x satisfying this criterion.
Please consult the NIST Digital Library of Mathematical Functions or the companion (2010) for a detailed discussion of the confluent hypergeometric function including special cases, transformations, relations and asymptotic approximations.

4 References

NIST Handbook of Mathematical Functions (2010) (eds F W J Olver, D W Lozier, R F Boisvert, C W Clark) Cambridge University Press
Pearson J (2009) Computation of hypergeometric functions MSc Dissertation, Mathematical Institute, University of Oxford

5 Arguments

1:   ANI – REAL (KIND=nag_wp)Input
On entry: ai, the nearest integer to a, satisfying ai = a-ar.
Constraints:
  • ANI=ANI;
  • ANI≤arbnd.
2:   ADR – REAL (KIND=nag_wp)Input
On entry: ar, the signed decimal remainder satisfying ar = a-ai and ar ≤ 0.5.
Constraint: ADR≤0.5.
Note: if ADR<100.0 ε, ar=0.0 will be used, where ε is the machine precision as returned by X02AJF.
3:   BNI – REAL (KIND=nag_wp)Input
On entry: bi, the nearest integer to b, satisfying bi=b-br.
Constraints:
  • BNI=BNI;
  • BNI≤arbnd;
  • if BDR=0.0, BNI>0.
4:   BDR – REAL (KIND=nag_wp)Input
On entry: br, the signed decimal remainder satisfying br = b-bi and br ≤ 0.5.
Constraint: BDR≤0.5.
Note: if BDR-ADR<100.0 ε, ar=br will be used, where ε is the machine precision as returned by X02AJF.
5:   X – REAL (KIND=nag_wp)Input
On entry: the argument x of the function.
Constraint: X≤arbnd.
6:   FRM – REAL (KIND=nag_wp)Output
On exit: mf, the scaled real component of the solution satisfying mf=M a,b,x×2-ms.
Note: if overflow occurs upon completion, as indicated by IFAIL=2, the value of mf returned may still be correct. If overflow occurs in a subcalculation, as indicated by IFAIL=5, this should not be assumed.
7:   SCM – INTEGEROutput
On exit: ms, the scaling power of two, satisfying ms= log 2 M a,b,x mf .
Note: if overflow occurs upon completion, as indicated by IFAIL=2, then ms≥Imax, where Imax is the largest representable integer (see X02BBF). If overflow occurs during a subcalculation, as indicated by IFAIL=5, ms may or may not be greater than Imax. In either case, SCM=X02BBF will have been returned.
8:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
Underflow occurred during the evaluation of M a,b,x.
The returned value may be inaccurate.
IFAIL=2
On completion, overflow occurred in the evaluation of M a,b,x.
IFAIL=3
All approximations have completed, and the final residual estimate indicates some precision may have been lost.
Relative residual =value.
IFAIL=4
All approximations have completed, and the final residual estimate indicates no accuracy can be guaranteed.
Relative residual =value.
IFAIL=5
Overflow occurred in a subcalculation of M a,b,x.
The answer may be completely incorrect.
IFAIL=11
On entry, ANI=value.
Constraint: ANI≤arbnd=value.
IFAIL=13
ANI is non-integral.
On entry, ANI=value.
Constraint: ANI=ANI.
IFAIL=21
On entry, ADR=value.
Constraint: ADR≤0.5.
IFAIL=31
On entry, BNI=value.
Constraint: BNI≤arbnd=value.
IFAIL=32
On entry, b=BNI+BDR=value.
M a,b,x is undefined when b is zero or a negative integer.
IFAIL=33
BNI is non-integral.
On entry, BNI=value.
Constraint: BNI=BNI.
IFAIL=41
On entry, BDR=value.
Constraint: BDR≤0.5.
IFAIL=51
On entry, X=value.
Constraint: X≤arbnd=value.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

In general, if IFAIL=0, the value of M may be assumed accurate, with the possible loss of one or two decimal places. Assuming the result does not under or overflow, an error estimate res is made internally using equation (1). If the magnitude of res is sufficiently large a nonzero IFAIL will be returned. Specifically,
IFAIL=0 | res≤1000 ε
IFAIL=3 | 1000 ε<res≤0.1
IFAIL=4 | res>0.1
A further estimate of the residual can be constructed using equation (1), and the differential identity,
d M a,b,x dx = ab M a+1,b+1,x , d 2 M a,b,x d x 2 = a a+1 b b+1 M a+2,b+2,x .
This estimate is however dependent upon the error involved in approximating M a+1,b+1,x and M a+2,b+2,x .

8 Parallelism and Performance

S22BBF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
S22BBF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

The values of mf and ms are implementation dependent. In most cases, if F 1 1 a;b;x = 0 , m f = 0 and m s = 0 will be returned, and if F 1 1 a;b;x = 0 is finite, the fractional component will be bound by 0.5 ≤ m f < 1, with m s chosen accordingly.
The values returned in FRM (mf) and SCM (ms) may be used to explicitly evaluate M a,b,x, and may also be used to evaluate products and ratios of multiple values of M as follows,
M a,b,x = mf × 2 ms M a 1,b 1,x 1 × M a 2,b 2,x 2 = m f 1 × m f 2 × 2 m s 1 + m s 2 M a 1,b 1,x 1 M a 2,b 2,x 2 = m f 1 m f 2 × 2 m s 1 - m s 2 ln M a,b,x = ln mf + ms × ln 2 .

10 Example

This example evaluates the confluent hypergeometric function at two points in scaled form using S22BBF, and subsequently calculates their product and ratio without having to explicitly construct M.

10.1 Program Text

Program Text (s22bbfe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (s22bbfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S22BEF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S22BEF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S22BEF returns a value for the Gauss hypergeometric function F 1 2 a,b;c;x for real parameters a,b and c, and real argument x.

2 Specification

FUNCTION S22BEF ( A, B, C, X, IFAIL)
REAL (KIND=nag_wp) S22BEF
INTEGER | IFAIL
REAL (KIND=nag_wp) | A, B, C, X

3 Description

S22BEF returns a value for the Gauss hypergeometric function F 1 2 a,b;c;x for real parameters a, b and c, and for real argument x.
The associated routine S22BFF performs the same operations, but returns F 1 2 a,b;c;x in the scaled form F 1 2 a,b;c;x=ffr×2 fsc to allow calculations to be performed when F 1 2 a,b;c;x is not representable as a single working precision number. It also accepts the parameters a, b and c as summations of an integer and a decimal fraction, giving higher accuracy when any are close to an integer.
The Gauss hypergeometric function is a solution to the hypergeometric differential equation,
x 1-x d 2 f d x 2 + c-a+b+1 x d f dx - a b f = 0 . (1)
For x<1, it may be defined by the Gauss series,
F 1 2 a,b;c;x = ∑ s=0 ∞ a s b s c s s! xs = 1+ ab c x + a a+1 b b+1 c c+1 2! x 2 + ⋯ , (2)
where a s=1 aa+1a+2…a+s-1 is the rising factorial of a. F 1 2 a,b;c;x is undefined for c=0 or c a negative integer.
For x<1, the series is absolutely convergent and F 1 2 a,b;c;x is finite.
For x<1, linear transformations of the form,
F 1 2 a,b;c;x = C 1 a 1,b 1,c 1,x 1 F 1 2 a 1, b 1 ;c 1;x 1 + C 2 a 2,b 2,c 2,x 2 F 1 2 a 2, b 2 ;c 2;x 2 (3)
exist, where x 1, x 2∈0,1. C 1 and C 2 are real valued functions of the parameters and argument, typically involving products of gamma functions. When these are degenerate, finite limiting cases exist. Hence for x<0, F 1 2 a,b;c;x is defined by analytic continuation, and for x<1, F 1 2 a,b;c;x is real and finite.
For x=1, the following apply:
  • If c>a+b, F 1 2 a,b;c;1 = Γ c Γ c-a-b Γ c-a Γ c-b , and hence is finite. Solutions also exist for the degenerate cases where c-a or c-b are negative integers or zero.
  • If c≤a+b, F 1 2 a,b;c;1 is infinite, and the sign of F 1 2 a,b;c;1 is determinable as x approaches 1 from below.
In the complex plane, the principal branch of F 1 2 a,b;c;z is taken along the real axis from x=1.0 increasing. F 1 2 a,b;c;z is multivalued along this branch, and for real parameters a,b and c is typically not real valued. As such, this routine will not compute a solution when x>1.
The solution strategy used by this routine is primarily dependent upon the value of the argument x. Once trivial cases and the case x=1.0 are eliminated, this proceeds as follows.
For 0<x≤0.5, sets of safe parameters α i,j;β i,j;ζ i,j; χj 1≤j≤2 ;1≤i≤4 are determined, such that the values of F 1 2 aj,bj;cj;xj required for an appropriate transformation of the type (3) may be calculated either directly or using recurrence relations from the solutions of F 1 2 α i,j,β i,j ;ζ i,j;χj . If c is positive, then only transformations with C 2=0.0 will be used, implying only F 1 2 a 1,b 1;c 1;x 1 will be required, with the transformed argument x 1=x. If c is negative, in some cases a transformation with C 2≠0.0 will be used, with the argument x 2=1.0-x. The routine then cycles through these sets until acceptable solutions are generated. If no computation produces an accurate answer, the least inaccurate answer is selected to complete the computation. See Section 7.
For 0.5<x<1.0, an identical approach is first used with the argument x. Should this fail, a linear transformation resulting in both transformed arguments satisfying xj=1.0-x is employed, and the above strategy for 0<x≤0.5 is utilized on both components. Further transformations in these sub-computations are however limited to single terms with no argument transformation.
For x<0, a linear transformation mapping the argument x to the interval 0,0.5 is first employed. The strategy for 0<x≤0.5 is then used on each component, including possible further two term transforms. To avoid some degenerate cases, a transform mapping the argument x to 0.5,1 may also be used.
In addition to the above restrictions on c and x, an artificial bound, arbnd, is placed on the magnitudes of a,b,c and x to minimize the occurrence of overflow in internal calculations, particularly those involving real to integer conversions. arbnd=0.0001×Imax, where Imax is the largest machine integer (see X02BBF). It should however not be assumed that this routine will produce accurate answers for all values of a,b,c and x satisfying this criterion.
This routine also tests for non-finite values of the parameters and argument on entry, and assigns non-finite values upon completion if appropriate. See Section 9 and Chapter X07.
Please consult the NIST Digital Library of Mathematical Functions or the companion (2010) for a detailed discussion of the Gauss hypergeometric function including special cases, transformations, relations and asymptotic approximations.

4 References

NIST Handbook of Mathematical Functions (2010) (eds F W J Olver, D W Lozier, R F Boisvert, C W Clark) Cambridge University Press
Pearson J (2009) Computation of hypergeometric functions MSc Dissertation, Mathematical Institute, University of Oxford

5 Arguments

1:   A – REAL (KIND=nag_wp)Input
On entry: the parameter a.
Constraint: A≤arbnd.
2:   B – REAL (KIND=nag_wp)Input
On entry: the parameter b.
Constraint: B≤arbnd.
3:   C – REAL (KIND=nag_wp)Input
On entry: the parameter c.
Constraints:
  • C≤arbnd;
  • C≠0,-1,-2,….
4:   X – REAL (KIND=nag_wp)Input
On entry: the argument x.
Constraint: -arbnd<X≤1.
5:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
Underflow occurred during the evaluation of F 1 2 a,b; c;x . The returned value may be inaccurate.
IFAIL=2
All approximations have completed, and the final residual estimate indicates some precision may have been lost.
Relative residual=value.
IFAIL=3
All approximations have completed, and the final residual estimate indicates no accuracy can be guaranteed.
Relative residual=value.
IFAIL=4
On entry, X=value, c=value, a+b=value.
F 1 2 a,b; c;1 is infinite in the case c≤a+b.
IFAIL=5
On completion, overflow occurred in the evaluation of F 1 2 a,b; c;x .
IFAIL=6
Overflow occurred in a subcalculation of F 1 2 a,b; c;x . The result may or may not be infinite.
IFAIL=9
An internal calculation has resulted in an undefined result.
IFAIL=11
On entry, A does not satisfy A≤arbnd=value.
IFAIL=21
On entry, B does not satisfy B≤arbnd=value.
IFAIL=31
On entry, C does not satisfy C≤arbnd=value.
IFAIL=32
On entry, C=value.
F 1 2 a,b; c;x is undefined when c is zero or a negative integer.
IFAIL=41
On entry, X does not satisfy X≤arbnd=value.
IFAIL=42
On entry, X=value.
In general, F 1 2 a,b; c;x is not real valued when x>1.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

In general, if IFAIL=0, the value of F 1 2 a,b;c;x may be assumed accurate, with the possible loss of one or two decimal places. Assuming the result does not under or overflow, an error estimate res is made internally using equation (1). If the magnitude of res is sufficiently large, a nonzero IFAIL will be returned. Specifically,
IFAIL=0 or 1 | res≤1000 ε
IFAIL=2 | 1000 ε<res≤0.1
IFAIL=3 | res>0.1
where ε is the machine precision as returned by X02AJF.
A further estimate of the residual can be constructed using equation (1), and the differential identity,
d F 1 2 a,b; c;x dx = ab c F 1 2 a+1,b+1; c+1;x d 2 F 1 2 a,b; c;x d x 2 = a a+1 b b+1 c c+1 F 1 2 a+2,b+2; c+2;x (4)
This estimate is however dependent upon the error involved in approximating F 1 2 a+1,b+1; c+1;x and F 1 2 a+2,b+2; c+2;x .
Furthermore, the accuracy of the solution, and the error estimate, can be dependent upon the accuracy of the decimal fraction of the input parameters a and b. For example, if c=ci+cr=100+1.0E−6, then on a machine with 16 decimal digits of precision, the internal calculation of cr will only be accurate to 8 decimal places. This can subsequently pollute the final solution by several decimal places without affecting the residual estimate as greatly. Should you require higher accuracy in such regions, then you should use S22BFF, which requires you to supply the correct decimal fraction.

8 Parallelism and Performance

S22BEF is not threaded in any implementation.

9 Further Comments

S22BEF returns non-finite values when appropriate. See Chapter X07 for more information on the definitions of non-finite values.
Should a non-finite value be returned, this will be indicated in the value of IFAIL, as detailed in the following cases.
If IFAIL=0, or IFAIL=1, 2 or 3, a finite value will have been returned with an approximate accuracy as detailed in Section 7.
If IFAIL=4 then F 1 2 a,b;c;x is infinite, and a signed infinity will have been returned. The sign of the infinity should be correct when taking the limit as x approaches 1 from below.
If IFAIL=5 then upon completion, F 1 2 a,b;c;x > Rmax , where Rmax is the largest machine number given by X02ALF, and hence is too large to be representable. The result will be returned as a signed infinity. The sign should be correct.
If IFAIL=6 then overflow occurred during a subcalculation of F 1 2 a,b;c;x . A signed infinity will have been returned, however there is no guarantee that this is representative of either the magnitude or the sign of F 1 2 a,b;c;x .
For all other error exits, S22BEF will return a signalling NaN (see X07BBF).
If IFAIL=9 then an internal computation produced an undefined result. This may occur when two terms overflow with opposite signs, and the result is dependent upon their summation for example.
If IFAIL=32 then c is too close to a negative integer or zero on entry, and F 1 2 a,b;c;x is considered undefined. Note, this will also be the case when c is a negative integer, and a (possibly trivial) linear transformation of the form (3) would result in either:
(i) | all cj not being negative integers,
(ii) | for any cj which remain as negative integers, one of the corresponding parameters aj or bj is a negative integer of magnitude less than cj.
In the first case, the transformation coefficients Cj aj,bj,cj,xj are typically either infinite or undefined, preventing a solution being constructed. In the second case, the series (2) will terminate before the degenerate term, resulting in a polynomial of fixed degree, and hence potentially a finite solution.
If IFAIL=11, 21, 31 or 41 then no computation will have been performed. The actual solution may however be finite.
IFAIL=42 indicates x>1. Hence the requested solution is on the boundary of the principal branch of F 1 2 a,b;c;x , and hence is multivalued, typically with a nonzero imaginary component. It is however strictly finite.

10 Example

This example evaluates F 1 2 a,b;c;x at a fixed set of parameters a,b and c, and for several values for the argument x.

10.1 Program Text

Program Text (s22befe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (s22befe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S22BFF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S22BFF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S22BFF returns a value for the Gauss hypergeometric function F 1 2 a,b;c;x for real parameters a,b and c, and real argument x. The result is returned in the scaled form F 1 2 a,b;c;x = ffr × 2 fsc .

2 Specification

SUBROUTINE S22BFF ( ANI, ADR, BNI, BDR, CNI, CDR, X, FRF, SCF, IFAIL)
INTEGER | SCF, IFAIL
REAL (KIND=nag_wp) | ANI, ADR, BNI, BDR, CNI, CDR, X, FRF

3 Description

S22BFF returns a value for the Gauss hypergeometric function F 1 2 a,b;c;x for real parameters a, b and c, and for real argument x.
The Gauss hypergeometric function is a solution to the hypergeometric differential equation,
x 1-x d 2 f d x 2 + c- a+b+1 x d f dx - ab f = 0 . (1)
For x<1, it may be defined by the Gauss series,
F 1 2 a,b;c;x = ∑ s=0 ∞ a s b s c s s! xs = 1+ ab c x + a a+1 b b+1 c c+1 2! x 2 + ⋯ , (2)
where a s = 1 a a+1 a+2 … a+s-1 is the rising factorial of a . F 1 2 a,b;c;x is undefined for c=0 or c a negative integer.
For x<1, the series is absolutely convergent and F 1 2 a,b;c;x is finite.
For x<1, linear transformations of the form,
F 1 2 a,b;c;x = C 1 a 1,b 1,c 1,x 1 F 1 2 a 1, b 1 ;c 1;x 1 + C 2 a 2,b 2,c 2,x 2 F 1 2 a 2, b 2 ;c 2;x 2 (3)
exist, where x 1, x 2∈0,1. C 1 and C 2 are real valued functions of the parameters and argument, typically involving products of gamma functions. When these are degenerate, finite limiting cases exist. Hence for x<0, F 1 2 a,b;c;x is defined by analytic continuation, and for x<1, F 1 2 a,b;c;x is real and finite.
For x=1, the following apply:
  • If c>a+b, F 1 2 a,b;c;1 = Γ c Γ c-a-b Γ c-a Γ c-b , and hence is finite. Solutions also exist for the degenerate cases where c-a or c-b are negative integers or zero.
  • If c≤a+b, F 1 2 a,b;c;1 is infinite, and the sign of F 1 2 a,b;c;1 is determinable as x approaches 1 from below.
In the complex plane, the principal branch of F 1 2 a,b;c;z is taken along the real axis from x=1.0 increasing. F 1 2 a,b;c;z is multivalued along this branch, and for real parameters a,b and c is typically not real valued. As such, this routine will not compute a solution when x>1.
The solution strategy used by this routine is primarily dependent upon the value of the argument x. Once trivial cases and the case x=1.0 are eliminated, this proceeds as follows.
For 0<x≤0.5, sets of safe parameters α i,j,β i,j,ζ i,j, χj 1≤j≤2 ,1≤i≤4 are determined, such that the values of F 1 2 aj, bj ;cj;xj required for an appropriate transformation of the type (3) may be calculated either directly or using recurrence relations from the solutions of F 1 2 α i,j , β i,j ;ζ i,j;χj . If c is positive, then only transformations with C 2=0.0 will be used, implying only F 1 2 a 1, b 1 ;c 1;x 1 will be required, with the transformed argument x 1=x. If c is negative, in some cases a transformation with C 2≠0.0 will be used, with the argument x 2=1.0-x. The routine then cycles through these sets until acceptable solutions are generated. If no computation produces an accurate answer, the least inaccurate answer is selected to complete the computation. See Section 7.
For 0.5<x<1.0, an identical approach is first used with the argument x. Should this fail, a linear transformation resulting in both transformed arguments satisfying xj=1.0-x is employed, and the above strategy for 0<x≤0.5 is utilized on both components. Further transformations in these sub-computations are however limited to single terms with no argument transformation.
For x<0, a linear transformation mapping the argument x to the interval 0,0.5 is first employed. The strategy for 0<x≤0.5 is then used on each component, including possible further two term transforms. To avoid some degenerate cases, a transform mapping the argument x to 0.5,1 may also be used.
For improved precision in the final result, this routine accepts a,b and c split into an integral and a decimal fractional component. Specifically, a=ai+ar, where ar≤0.5 and ai=a-ar is integral. The other parameters b and c are similarly deconstructed.
In addition to the above restrictions on c and x, an artificial bound, arbnd, is placed on the magnitudes of a,b,c and x to minimize the occurrence of overflow in internal calculations, particularly those involving real to integer conversions. arbnd=0.0001×Imax, where Imax is the largest machine integer (see X02BBF). It should however not be assumed that this routine will produce accurate answers for all values of a,b,c and x satisfying this criterion.
This routine also tests for non-finite values of the parameters and argument on entry, and assigns non-finite values upon completion if appropriate. See Section 9 and Chapter X07.
Please consult the NIST Digital Library of Mathematical Functions or the companion (2010) for a detailed discussion of the Gauss hypergeometric function including special cases, transformations, relations and asymptotic approximations.

4 References

NIST Handbook of Mathematical Functions (2010) (eds F W J Olver, D W Lozier, R F Boisvert, C W Clark) Cambridge University Press
Pearson J (2009) Computation of hypergeometric functions MSc Dissertation, Mathematical Institute, University of Oxford

5 Arguments

1:   ANI – REAL (KIND=nag_wp)Input
On entry: ai, the nearest integer to a, satisfying ai = a-ar.
Constraints:
  • ANI=ANI;
  • ANI≤arbnd.
2:   ADR – REAL (KIND=nag_wp)Input
On entry: ar, the signed decimal remainder satisfying ar = a-ai and ar ≤ 0.5.
Constraint: ADR≤0.5.
3:   BNI – REAL (KIND=nag_wp)Input
On entry: bi, the nearest integer to b, satisfying bi = b-br.
Constraints:
  • BNI=BNI;
  • BNI≤arbnd.
4:   BDR – REAL (KIND=nag_wp)Input
On entry: br, the signed decimal remainder satisfying br = b-bi and br ≤ 0.5.
Constraint: BDR≤0.5.
5:   CNI – REAL (KIND=nag_wp)Input
On entry: ci, the nearest integer to c, satisfying ci=c-cr.
Constraints:
  • CNI=CNI;
  • CNI≤arbnd;
  • if CDR<16.0 ε, CNI≥1.0.
6:   CDR – REAL (KIND=nag_wp)Input
On entry: cr, the signed decimal remainder satisfying cr = c-ci and cr ≤ 0.5.
Constraint: CDR≤0.5.
7:   X – REAL (KIND=nag_wp)Input
On entry: the argument x.
Constraint: -arbnd<X≤1.
8:   FRF – REAL (KIND=nag_wp)Output
On exit: ffr, the scaled real component of the solution satisfying ffr = F 1 2 a,b;c;x × 2 -fsc , i.e., F 1 2 a,b;c;x = ffr × 2 fsc. See Section 9 for the behaviour of ffr when a finite or non-finite answer is returned.
9:   SCF – INTEGEROutput
On exit: fsc, the scaling power of two, satisfying fsc = log 2 F 1 2 a,b;c;x ffr , i.e., F 1 2 a,b;c;x = ffr × 2 fsc. See Section 9 for the behaviour of fsc when a non-finite answer is returned.
10:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
Underflow occurred during the evaluation of F 1 2 a,b;c;x . The returned value may be inaccurate.
IFAIL=2
All approximations have completed, and the final residual estimate indicates some precision may have been lost.
Relative residual=value.
IFAIL=3
All approximations have completed, and the final residual estimate indicates no accuracy can be guaranteed.
Relative residual=value.
IFAIL=4
On entry, X=value, c=value, a+b=value.
F 1 2 a,b;c;1 is infinite in the case c≤a+b.
IFAIL=5
On completion, overflow occurred in the evaluation of F 1 2 a,b;c;x .
IFAIL=6
Overflow occurred in a subcalculation of F 1 2 a,b;c;x . The answer may be completely incorrect.
IFAIL=9
An internal calculation has resulted in an undefined result.
IFAIL=11
On entry, ANI does not satisfy ANI≤arbnd=value.
IFAIL=13
ANI is non-integral.
On entry, ANI=value.
Constraint: ANI=ANI.
IFAIL=21
On entry, ADR does not satisfy ADR≤0.5.
IFAIL=31
On entry, BNI does not satisfy BNI≤arbnd=value.
IFAIL=33
BNI is non-integral.
On entry, BNI=value.
Constraint: BNI=BNI.
IFAIL=41
On entry, BDR does not satisfy BDR≤0.5.
IFAIL=51
On entry, CNI does not satisfy CNI≤arbnd=value.
IFAIL=52
On entry, c=CNI+CDR=value.
F 1 2 a,b;c;x is undefined when c is zero or a negative integer.
IFAIL=53
CNI is non-integral.
On entry, CNI=value.
Constraint: CNI=CNI.
IFAIL=61
On entry, CDR does not satisfy CDR≤0.5.
IFAIL=71
On entry, X does not satisfy X≤arbnd=value.
IFAIL=72
On entry, X=value.
In general, F 1 2 a,b;c;x is not real valued when x>1.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

In general, if IFAIL=0, the value of F 1 2 a,b;c;x may be assumed accurate, with the possible loss of one or two decimal places. Assuming the result does not overflow, an error estimate res is made internally using equation (1). If the magnitude of this residual res is sufficiently large, a nonzero IFAIL will be returned. Specifically,
IFAIL=0 or 1 | res≤1000 ε
IFAIL=2 | 1000 ε<res≤0.1
IFAIL=3 | res>0.1
where ε is the machine precision as returned by X02AJF. Note that underflow may also have occurred if IFAIL=2 or 3.
A further estimate of the residual can be constructed using equation (1), and the differential identity,
d F 1 2 a,b;c;x dx = ab c F 1 2 a+1, b+1 ;c+1;x d 2 F 1 2 a,b;c;x d x 2 = a a+1 b b+1 c c+1 F 1 2 a+2, b+2 ;c+2;x (4)
This estimate is however dependent upon the error involved in approximating F 1 2 a+1, b+1 ;c+1;x and F 1 2 a+2, b+2 ;c+2;x .

8 Parallelism and Performance

S22BFF is not threaded in any implementation.

9 Further Comments

S22BFF returns non-finite values when appropriate. See Chapter X07 for more information on the definitions of non-finite values.
Should a non-finite value be returned, this will be indicated in the value of IFAIL, as detailed in the following cases.
If IFAIL=0 or IFAIL=1, 2 or 3, a finite value will have been returned with approximate accuracy as detailed in Section 7.
The values of f fr and f sc are implementation dependent. In most cases, if F 1 2 a,b;c;x = 0 , f fr = 0 and f sc = 0 will be returned, and if F 1 2 a,b;c;x is finite, the fractional component will be bound by 0.5 ≤ f fr < 1, with f sc chosen accordingly.
The values returned in FRF (ffr) and SCF (fsc) may be used to explicitly evaluate F 1 2 a,b;c;x , and may also be used to evaluate products and ratios of multiple values of F 1 2 as follows,
F 1 2 a,b;c;x = ffr × 2 fsc F 1 2 a 1, b 1 ;c 1;x 1 × F 1 2 a 2, b 2 ;c 2;x 2 = f fr 1 × f fr 2 × 2 f sc 1 + f sc 2 F 1 2 a 1, b 1 ;c 1;x 1 F 1 2 a 2, b 2 ;c 2;x 2 = f fr 1 f fr 2 × 2 f sc 1 - f sc 2 ln F 1 2 a,b;c;x = ln ffr + fsc × ln 2 .
If IFAIL=4 then F 1 2 a,b;c;x is infinite. A signed infinity will have been returned for FRF, and SCF=0. The sign of FRF should be correct when taking the limit as x approaches 1 from below.
If IFAIL=5 then upon completion, F 1 2 a,b;c;x > 2 Imax , where Imax is given by X02BBF, and hence is too large to be representable even in the scaled form. The scaled real component returned in FRF may still be correct, whilst SCF=Imax will have been returned.
If IFAIL=6 then overflow occurred during a subcalculation of F 1 2 a,b;c;x . The same result as for IFAIL=5 will have been returned, however there is no guarantee that this is representative of either the magnitude of the scaling power fsc, or the scaled component ffr of F 1 2 a,b;c;x .
For all other error exits, SCF=0 will be returned and FRF will be returned as a signalling NaN (see X07BBF).
If IFAIL=9 an internal computation produced an undefined result. This may occur when two terms overflow with opposite signs, and the result is dependent upon their summation for example.
If IFAIL=52 then c is too close to a negative integer or zero on entry, and F 1 2 a,b;c;x is undefined. Note, this will also be the case when c is a negative integer, and a (possibly trivial) linear transformation of the form (3) would result in either:
(i) | all cj not being negative integers,
(ii) | for any cj which remain as negative integers, one of the corresponding parameters aj or bj is a negative integer of magnitude less than cj.
In the first case, the transformation coefficients Cj aj,bj,cj,xj are typically either infinite or undefined, preventing a solution being constructed. In the second case, the series (2) will terminate before the degenerate term, resulting in a polynomial of fixed degree, and hence potentially a finite solution.
If IFAIL=11, 31, 51 or 71 then no computation will have been performed due to the risk of integer overflow. The actual solution may however be finite.
IFAIL=72 indicates x>1, and hence the requested solution is on the boundary of the principal branch of F 1 2 a,b;c;x . Hence it is multivalued, typically with a nonzero imaginary component. It is however strictly finite.

10 Example

This example evaluates the Gauss hypergeometric function at two points in scaled form using S22BFF, and subsequently calculates their product and ratio implicitly.

10.1 Program Text

Program Text (s22bffe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (s22bffe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S30AAF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S30AAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S30AAF computes the European option price given by the Black–Scholes–Merton formula.

2 Specification

SUBROUTINE S30AAF ( CALPUT, M, N, X, S, T, SIGMA, R, Q, P, LDP, IFAIL)
INTEGER | M, N, LDP, IFAIL
REAL (KIND=nag_wp) | X(M), S, T(N), SIGMA, R, Q, P(LDP,N)
CHARACTER(1) | CALPUT

3 Description

S30AAF computes the price of a European call (or put) option for constant volatility, σ, and risk-free interest rate, r, with a possible dividend yield, q, using the Black–Scholes–Merton formula (see Black and Scholes (1973) and Merton (1973)). For a given strike price, X, the price of a European call with underlying price, S, and time to expiry, T, is
Pcall = S e-qT Φ d 1 - X e-rT Φ d 2
and the corresponding European put price is
Pput = X e-rT Φ-d 2 - S e-qT Φ-d 1
and where Φ denotes the cumulative Normal distribution function,
Φ x = 1 2 π ∫ -∞ x exp -y 2/2 dy
and
d 1 = ln S/X + r-q+ σ 2 / 2 T σ⁢T , d 2 = d 1 - σ⁢T .
The option price P ij=P X=Xi,T=Tj is computed for each strike price in a set Xi, i=1,2,…,m, and for each expiry time in a set Tj, j=1,2,…,n.

4 References

Black F and Scholes M (1973) The pricing of options and corporate liabilities Journal of Political Economy 81 637–654
Merton R C (1973) Theory of rational option pricing Bell Journal of Economics and Management Science 4 141–183

5 Arguments

1:   CALPUT – CHARACTER(1)Input
On entry: determines whether the option is a call or a put.
CALPUT='C'
A call; the holder has a right to buy.
CALPUT='P'
A put; the holder has a right to sell.
Constraint: CALPUT='C' or 'P'.
2:   M – INTEGERInput
On entry: the number of strike prices to be used.
Constraint: M≥1.
3:   N – INTEGERInput
On entry: the number of times to expiry to be used.
Constraint: N≥1.
4:   X M – REAL (KIND=nag_wp) arrayInput
On entry: X i must contain Xi, the ith strike price, for i=1,2,…,M.
Constraint: X i≥z ​ and ​ X i ≤ 1 / z , where z = X02AMF , the safe range parameter, for i=1,2,…,M.
5:   S – REAL (KIND=nag_wp)Input
On entry: S, the price of the underlying asset.
Constraint: S≥z ​ and ​S≤1.0/z, where z=X02AMF, the safe range parameter.
6:   T N – REAL (KIND=nag_wp) arrayInput
On entry: T i must contain Ti, the ith time, in years, to expiry, for i=1,2,…,N.
Constraint: T i≥z, where z = X02AMF , the safe range parameter, for i=1,2,…,N.
7:   SIGMA – REAL (KIND=nag_wp)Input
On entry: σ, the volatility of the underlying asset. Note that a rate of 15% should be entered as 0.15.
Constraint: SIGMA>0.0.
8:   R – REAL (KIND=nag_wp)Input
On entry: r, the annual risk-free interest rate, continuously compounded. Note that a rate of 5% should be entered as 0.05.
Constraint: R≥0.0.
9:   Q – REAL (KIND=nag_wp)Input
On entry: q, the annual continuous yield rate. Note that a rate of 8% should be entered as 0.08.
Constraint: Q≥0.0.
10:   P LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: P ij contains P ij, the option price evaluated for the strike price Xi at expiry Tj for i=1,2,…,M and j=1,2,…,N.
11:   LDP – INTEGERInput
On entry: the first dimension of the array P as declared in the (sub)program from which S30AAF is called.
Constraint: LDP≥M.
12:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, CALPUT=value was an illegal value.
IFAIL=2
On entry, M=value.
Constraint: M≥1.
IFAIL=3
On entry, N=value.
Constraint: N≥1.
IFAIL=4
On entry, X value=value.
Constraint: X i≥value and X i≤value.
IFAIL=5
On entry, S=value.
Constraint: S≥value and S≤value.
IFAIL=6
On entry, T value=value.
Constraint: T i≥value.
IFAIL=7
On entry, SIGMA=value.
Constraint: SIGMA>0.0.
IFAIL=8
On entry, R=value.
Constraint: R≥0.0.
IFAIL=9
On entry, Q=value.
Constraint: Q≥0.0.
IFAIL=11
On entry, LDP=value and M=value.
Constraint: LDP≥M.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The accuracy of the output is dependent on the accuracy of the cumulative Normal distribution function, Φ. This is evaluated using a rational Chebyshev expansion, chosen so that the maximum relative error in the expansion is of the order of the machine precision (see S15ABF and S15ADF). An accuracy close to machine precision can generally be expected.

8 Parallelism and Performance

S30AAF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

None.

10 Example

This example computes the prices for six European call options using two expiry times and three strike prices as input. The times to expiry are taken as 0.7 and 0.8 years respectively. The stock price is 55, with strike prices, 58, 60 and 62. The risk-free interest rate is 10% per year and the volatility is 30% per year.

10.1 Program Text

Program Text (s30aafe.f90)

10.2 Program Data

Program Data (s30aafe.d)

10.3 Program Results

Program Results (s30aafe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S30ABF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S30ABF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S30ABF computes the European option price given by the Black–Scholes–Merton formula together with its sensitivities (Greeks).

2 Specification

SUBROUTINE S30ABF ( CALPUT, M, N, X, S, T, SIGMA, R, Q, P, LDP, DELTA, GAMMA, VEGA, THETA, RHO, CRHO, VANNA, CHARM, SPEED, COLOUR, ZOMMA, VOMMA, IFAIL)
INTEGER | M, N, LDP, IFAIL
REAL (KIND=nag_wp) | X(M), S, T(N), SIGMA, R, Q, P(LDP,N), DELTA(LDP,N), GAMMA(LDP,N), VEGA(LDP,N), THETA(LDP,N), RHO(LDP,N), CRHO(LDP,N), VANNA(LDP,N), CHARM(LDP,N), SPEED(LDP,N), COLOUR(LDP,N), ZOMMA(LDP,N), VOMMA(LDP,N)
CHARACTER(1) | CALPUT

3 Description

S30ABF computes the price of a European call (or put) option together with the Greeks or sensitivities, which are the partial derivatives of the option price with respect to certain of the other input parameters, by the Black–Scholes–Merton formula (see Black and Scholes (1973) and Merton (1973)). The annual volatility, σ, risk-free interest rate, r, and dividend yield, q, must be supplied as input. For a given strike price, X, the price of a European call with underlying price, S, and time to expiry, T, is
Pcall = S e-qT Φ d 1 - X e-rT Φ d 2
and the corresponding European put price is
Pput = X e-rT Φ-d 2 - S e-qT Φ-d 1
and where Φ denotes the cumulative Normal distribution function,
Φ x = 1 2 π ∫ -∞ x exp -y 2/2 dy
and
d 1 = ln S/X + r-q+ σ 2 / 2 T σ⁢T , d 2 = d 1 - σ⁢T .
The option price P ij=P X=Xi,T=Tj is computed for each strike price in a set Xi, i=1,2,…,m, and for each expiry time in a set Tj, j=1,2,…,n.

4 References

Black F and Scholes M (1973) The pricing of options and corporate liabilities Journal of Political Economy 81 637–654
Merton R C (1973) Theory of rational option pricing Bell Journal of Economics and Management Science 4 141–183

5 Arguments

1:   CALPUT – CHARACTER(1)Input
On entry: determines whether the option is a call or a put.
CALPUT='C'
A call; the holder has a right to buy.
CALPUT='P'
A put; the holder has a right to sell.
Constraint: CALPUT='C' or 'P'.
2:   M – INTEGERInput
On entry: the number of strike prices to be used.
Constraint: M≥1.
3:   N – INTEGERInput
On entry: the number of times to expiry to be used.
Constraint: N≥1.
4:   X M – REAL (KIND=nag_wp) arrayInput
On entry: X i must contain Xi, the ith strike price, for i=1,2,…,M.
Constraint: X i≥z ​ and ​ X i ≤ 1 / z , where z = X02AMF , the safe range parameter, for i=1,2,…,M.
5:   S – REAL (KIND=nag_wp)Input
On entry: S, the price of the underlying asset.
Constraint: S≥z ​ and ​S≤1.0/z, where z=X02AMF, the safe range parameter.
6:   T N – REAL (KIND=nag_wp) arrayInput
On entry: T i must contain Ti, the ith time, in years, to expiry, for i=1,2,…,N.
Constraint: T i≥z, where z = X02AMF , the safe range parameter, for i=1,2,…,N.
7:   SIGMA – REAL (KIND=nag_wp)Input
On entry: σ, the volatility of the underlying asset. Note that a rate of 15% should be entered as 0.15.
Constraint: SIGMA>0.0.
8:   R – REAL (KIND=nag_wp)Input
On entry: r, the annual risk-free interest rate, continuously compounded. Note that a rate of 5% should be entered as 0.05.
Constraint: R≥0.0.
9:   Q – REAL (KIND=nag_wp)Input
On entry: q, the annual continuous yield rate. Note that a rate of 8% should be entered as 0.08.
Constraint: Q≥0.0.
10:   P LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: P ij contains P ij, the option price evaluated for the strike price Xi at expiry Tj for i=1,2,…,M and j=1,2,…,N.
11:   LDP – INTEGERInput
On entry: the first dimension of the arrays P, DELTA, GAMMA, VEGA, THETA, RHO, CRHO, VANNA, CHARM, SPEED, COLOUR, ZOMMA and VOMMA as declared in the (sub)program from which S30ABF is called.
Constraint: LDP≥M.
12:   DELTA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: the leading M×N part of the array DELTA contains the sensitivity, ∂P∂S, of the option price to change in the price of the underlying asset.
13:   GAMMA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: the leading M×N part of the array GAMMA contains the sensitivity, ∂2 P∂S 2, of DELTA to change in the price of the underlying asset.
14:   VEGA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: VEGA ij, contains the first-order Greek measuring the sensitivity of the option price P ij to change in the volatility of the underlying asset, i.e., ∂P ij ∂σ , for i=1,2,…,M and j=1,2,…,N.
15:   THETA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: THETA ij, contains the first-order Greek measuring the sensitivity of the option price P ij to change in time, i.e., - ∂P ij ∂T , for i=1,2,…,M and j=1,2,…,N, where b=r-q.
16:   RHO LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: RHO ij, contains the first-order Greek measuring the sensitivity of the option price P ij to change in the annual risk-free interest rate, i.e., - ∂P ij ∂r , for i=1,2,…,M and j=1,2,…,N.
17:   CRHO LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: CRHO ij, contains the first-order Greek measuring the sensitivity of the option price P ij to change in the annual cost of carry rate, i.e., - ∂P ij ∂b , for i=1,2,…,M and j=1,2,…,N, where b=r-q.
18:   VANNA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: VANNA ij, contains the second-order Greek measuring the sensitivity of the first-order Greek Δ ij to change in the volatility of the asset price, i.e., - ∂Δ ij ∂T = - ∂2 P ij ∂S∂σ , for i=1,2,…,M and j=1,2,…,N.
19:   CHARM LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: CHARM ij, contains the second-order Greek measuring the sensitivity of the first-order Greek Δ ij to change in the time, i.e., - ∂Δ ij ∂T = - ∂2 P ij ∂S∂T , for i=1,2,…,M and j=1,2,…,N.
20:   SPEED LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: SPEED ij, contains the third-order Greek measuring the sensitivity of the second-order Greek Γ ij to change in the price of the underlying asset, i.e., - ∂Γ ij ∂S = - ∂3 P ij ∂S 3 , for i=1,2,…,M and j=1,2,…,N.
21:   COLOUR LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: COLOUR ij, contains the third-order Greek measuring the sensitivity of the second-order Greek Γ ij to change in the time, i.e., - ∂Γ ij ∂T = - ∂3 P ij ∂S∂T , for i=1,2,…,M and j=1,2,…,N.
22:   ZOMMA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: ZOMMA ij, contains the third-order Greek measuring the sensitivity of the second-order Greek Γ ij to change in the volatility of the underlying asset, i.e., - ∂Γ ij ∂σ = - ∂3 P ij ∂S 2∂σ , for i=1,2,…,M and j=1,2,…,N.
23:   VOMMA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: VOMMA ij, contains the second-order Greek measuring the sensitivity of the first-order Greek Δ ij to change in the volatility of the underlying asset, i.e., - ∂Δ ij ∂σ = - ∂2 P ij ∂σ 2 , for i=1,2,…,M and j=1,2,…,N.
24:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, CALPUT=value was an illegal value.
IFAIL=2
On entry, M=value.
Constraint: M≥1.
IFAIL=3
On entry, N=value.
Constraint: N≥1.
IFAIL=4
On entry, X value=value.
Constraint: X i≥value and X i≤value.
IFAIL=5
On entry, S=value.
Constraint: S≥value and S≤value.
IFAIL=6
On entry, T value=value.
Constraint: T i≥value.
IFAIL=7
On entry, SIGMA=value.
Constraint: SIGMA>0.0.
IFAIL=8
On entry, R=value.
Constraint: R≥0.0.
IFAIL=9
On entry, Q=value.
Constraint: Q≥0.0.
IFAIL=11
On entry, LDP=value and M=value.
Constraint: LDP≥M.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The accuracy of the output is dependent on the accuracy of the cumulative Normal distribution function, Φ. This is evaluated using a rational Chebyshev expansion, chosen so that the maximum relative error in the expansion is of the order of the machine precision (see S15ABF and S15ADF). An accuracy close to machine precision can generally be expected.

8 Parallelism and Performance

S30ABF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

None.

10 Example

This example computes the price of a European put with a time to expiry of 0.7 years, a stock price of 55 and a strike price of 60. The risk-free interest rate is 10% per year and the volatility is 30% per year.

10.1 Program Text

Program Text (s30abfe.f90)

10.2 Program Data

Program Data (s30abfe.d)

10.3 Program Results

Program Results (s30abfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S30BAF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S30BAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S30BAF computes the price of a floating-strike lookback option.

2 Specification

SUBROUTINE S30BAF ( CALPUT, M, N, SM, S, T, SIGMA, R, Q, P, LDP, IFAIL)
INTEGER | M, N, LDP, IFAIL
REAL (KIND=nag_wp) | SM(M), S, T(N), SIGMA, R, Q, P(LDP,N)
CHARACTER(1) | CALPUT

3 Description

S30BAF computes the price of a floating-strike lookback call or put option. A call option of this type confers the right to buy the underlying asset at the lowest price, Smin, observed during the lifetime of the contract. A put option gives the holder the right to sell the underlying asset at the maximum price, Smax, observed during the lifetime of the contract. Thus, at expiry, the payoff for a call option is S-Smin, and for a put, Smax-S.
For a given minimum value the price of a floating-strike lookback call with underlying asset price, S, and time to expiry, T, is
Pcall = S e-qT Φ a 1 - Smin e-rT Φ a 2 + S e-rT σ 2 2 b S Smin -2 b / σ 2 Φ -a 1 + 2b σ T -e bT Φ -a 1 ,
where b=r-q≠0. The volatility, σ, risk-free interest rate, r, and annualised dividend yield, q, are constants. When r=q, the option price is given by
Pcall = S e-qT Φ a 1 - Smin e-rT Φ a 2 + S e-rT σ⁢T ϕ a 1 + a 1 Φ a 1 -1 .
The corresponding put price is (for b≠0),
Pput = Smax e-rT Φ -a 2 - S e-qT Φ -a 1 + S e-rT σ 2 2b - S Smax -2 b / σ 2 Φ a 1 - 2 b σ T + e bT Φ a 1 .
When r=q,
Pput = Smax e-rT Φ -a 2 - S e-qT Φ -a 1 + S e-rT σ⁢T ϕ a 1 + a 1 Φ a 1 .
In the above, Φ denotes the cumulative Normal distribution function,
Φ x = ∫ -∞ x ϕ y dy
where ϕ denotes the standard Normal probability density function
ϕ y = 1 2 π exp -y 2/2
and
a 1 = ln S / Sm + b + σ 2 / 2 T σ⁢T a 2=a 1-σ⁢T
where Sm is taken to be the minimum price attained by the underlying asset, Smin, for a call and the maximum price, Smax, for a put.
The option price P ij=P X=Xi,T=Tj is computed for each minimum or maximum observed price in a set Smin i or Smax i , i=1,2,…,m, and for each expiry time in a set Tj, j=1,2,…,n.

4 References

Goldman B M, Sosin H B and Gatto M A (1979) Path dependent options: buy at the low, sell at the high Journal of Finance 34 1111–1127

5 Arguments

1:   CALPUT – CHARACTER(1)Input
On entry: determines whether the option is a call or a put.
CALPUT='C'
A call; the holder has a right to buy.
CALPUT='P'
A put; the holder has a right to sell.
Constraint: CALPUT='C' or 'P'.
2:   M – INTEGERInput
On entry: the number of minimum or maximum prices to be used.
Constraint: M≥1.
3:   N – INTEGERInput
On entry: the number of times to expiry to be used.
Constraint: N≥1.
4:   SM M – REAL (KIND=nag_wp) arrayInput
On entry: SM i must contain Smin i , the ith minimum observed price of the underlying asset when CALPUT='C', or Smax i , the maximum observed price when CALPUT='P', for i=1,2,…,M.
Constraints:
  • SM i≥z ​ and ​ SM i ≤ 1 / z , where z = X02AMF , the safe range parameter, for i=1,2,…,M;
  • if CALPUT='C', SM i≤S, for i=1,2,…,M;
  • if CALPUT='P', SM i≥S, for i=1,2,…,M.
5:   S – REAL (KIND=nag_wp)Input
On entry: S, the price of the underlying asset.
Constraint: S≥z ​ and ​S≤1.0/z, where z=X02AMF, the safe range parameter.
6:   T N – REAL (KIND=nag_wp) arrayInput
On entry: T i must contain Ti, the ith time, in years, to expiry, for i=1,2,…,N.
Constraint: T i≥z, where z = X02AMF , the safe range parameter, for i=1,2,…,N.
7:   SIGMA – REAL (KIND=nag_wp)Input
On entry: σ, the volatility of the underlying asset. Note that a rate of 15% should be entered as 0.15.
Constraint: SIGMA>0.0.
8:   R – REAL (KIND=nag_wp)Input
On entry: r, the annual risk-free interest rate, continuously compounded. Note that a rate of 5% should be entered as 0.05.
Constraint: R≥0.0.
9:   Q – REAL (KIND=nag_wp)Input
On entry: q, the annual continuous yield rate. Note that a rate of 8% should be entered as 0.08.
Constraint: Q≥0.0.
10:   P LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: P ij contains P ij, the option price evaluated for the minimum or maximum observed price Smin i or Smax i at expiry Tj for i=1,2,…,M and j=1,2,…,N.
11:   LDP – INTEGERInput
On entry: the first dimension of the array P as declared in the (sub)program from which S30BAF is called.
Constraint: LDP≥M.
12:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, CALPUT=value was an illegal value.
IFAIL=2
On entry, M=value.
Constraint: M≥1.
IFAIL=3
On entry, N=value.
Constraint: N≥1.
IFAIL=4
On entry, SM value=value.
Constraint: value≤SM i≤value for all i.
On entry with a call option, SM value=value.
Constraint: for call options, SM i≤value for all i.
On entry with a put option, SM value=value.
Constraint: for put options, SM i≥value for all i.
IFAIL=5
On entry, S=value.
Constraint: S≥value and S≤value.
IFAIL=6
On entry, T value=value.
Constraint: T i≥value for all i.
IFAIL=7
On entry, SIGMA=value.
Constraint: SIGMA>0.0.
IFAIL=8
On entry, R=value.
Constraint: R≥0.0.
IFAIL=9
On entry, Q=value.
Constraint: Q≥0.0.
IFAIL=11
On entry, LDP=value and M=value.
Constraint: LDP≥M.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The accuracy of the output is dependent on the accuracy of the cumulative Normal distribution function, Φ. This is evaluated using a rational Chebyshev expansion, chosen so that the maximum relative error in the expansion is of the order of the machine precision (see S15ABF and S15ADF). An accuracy close to machine precision can generally be expected.

8 Parallelism and Performance

S30BAF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

None.

10 Example

This example computes the price of a floating-strike lookback call with a time to expiry of 6 months and a stock price of 120. The minimum price observed so far is 100. The risk-free interest rate is 10% per year and the volatility is 30% per year with an annual dividend return of 6%.

10.1 Program Text

Program Text (s30bafe.f90)

10.2 Program Data

Program Data (s30bafe.d)

10.3 Program Results

Program Results (s30bafe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S30BBF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S30BBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S30BBF computes the price of a floating-strike lookback option together with its sensitivities (Greeks).

2 Specification

SUBROUTINE S30BBF ( CALPUT, M, N, SM, S, T, SIGMA, R, Q, P, LDP, DELTA, GAMMA, VEGA, THETA, RHO, CRHO, VANNA, CHARM, SPEED, COLOUR, ZOMMA, VOMMA, IFAIL)
INTEGER | M, N, LDP, IFAIL
REAL (KIND=nag_wp) | SM(M), S, T(N), SIGMA, R, Q, P(LDP,N), DELTA(LDP,N), GAMMA(LDP,N), VEGA(LDP,N), THETA(LDP,N), RHO(LDP,N), CRHO(LDP,N), VANNA(LDP,N), CHARM(LDP,N), SPEED(LDP,N), COLOUR(LDP,N), ZOMMA(LDP,N), VOMMA(LDP,N)
CHARACTER(1) | CALPUT

3 Description

S30BBF computes the price of a floating-strike lookback call or put option, together with the Greeks or sensitivities, which are the partial derivatives of the option price with respect to certain of the other input parameters. A call option of this type confers the right to buy the underlying asset at the lowest price, Smin, observed during the lifetime of the contract. A put option gives the holder the right to sell the underlying asset at the maximum price, Smax, observed during the lifetime of the contract. Thus, at expiry, the payoff for a call option is S-Smin, and for a put, Smax-S.
For a given minimum value the price of a floating-strike lookback call with underlying asset price, S, and time to expiry, T, is
Pcall = S e-qT Φ a 1 - Smin e-rT Φ a 2 + S e-rT σ 2 2 b S Smin -2 b / σ 2 Φ -a 1 + 2b σ T -e bT Φ -a 1 ,
where b=r-q≠0. The volatility, σ, risk-free interest rate, r, and annualised dividend yield, q, are constants.
The corresponding put price is
Pput = Smax e-rT Φ -a 2 - S e-qT Φ -a 1 + S e-rT σ 2 2b - S Smax -2 b / σ 2 Φ a 1 - 2 b σ T + e bT Φ a 1 .
In the above, Φ denotes the cumulative Normal distribution function,
Φ x = ∫ -∞ x ϕ y dy
where ϕ denotes the standard Normal probability density function
ϕ y = 1 2 π exp -y 2/2
and
a 1 = ln S / Sm + b + σ 2 / 2 T σ⁢T a 2=a 1-σ⁢T
where Sm is taken to be the minimum price attained by the underlying asset, Smin, for a call and the maximum price, Smax, for a put.
The option price P ij=P X=Xi,T=Tj is computed for each minimum or maximum observed price in a set Smin i or Smax i , i=1,2,…,m, and for each expiry time in a set Tj, j=1,2,…,n.

4 References

Goldman B M, Sosin H B and Gatto M A (1979) Path dependent options: buy at the low, sell at the high Journal of Finance 34 1111–1127

5 Arguments

1:   CALPUT – CHARACTER(1)Input
On entry: determines whether the option is a call or a put.
CALPUT='C'
A call; the holder has a right to buy.
CALPUT='P'
A put; the holder has a right to sell.
Constraint: CALPUT='C' or 'P'.
2:   M – INTEGERInput
On entry: the number of minimum or maximum prices to be used.
Constraint: M≥1.
3:   N – INTEGERInput
On entry: the number of times to expiry to be used.
Constraint: N≥1.
4:   SM M – REAL (KIND=nag_wp) arrayInput
On entry: SM i must contain Smin i , the ith minimum observed price of the underlying asset when CALPUT='C', or Smax i , the maximum observed price when CALPUT='P', for i=1,2,…,M.
Constraints:
  • SM i≥z ​ and ​ SM i ≤ 1 / z , where z = X02AMF , the safe range parameter, for i=1,2,…,M;
  • if CALPUT='C', SM i≤S, for i=1,2,…,M;
  • if CALPUT='P', SM i≥S, for i=1,2,…,M.
5:   S – REAL (KIND=nag_wp)Input
On entry: S, the price of the underlying asset.
Constraint: S≥z ​ and ​S≤1.0/z, where z=X02AMF, the safe range parameter.
6:   T N – REAL (KIND=nag_wp) arrayInput
On entry: T i must contain Ti, the ith time, in years, to expiry, for i=1,2,…,N.
Constraint: T i≥z, where z = X02AMF , the safe range parameter, for i=1,2,…,N.
7:   SIGMA – REAL (KIND=nag_wp)Input
On entry: σ, the volatility of the underlying asset. Note that a rate of 15% should be entered as 0.15.
Constraint: SIGMA>0.0.
8:   R – REAL (KIND=nag_wp)Input
On entry: the annual risk-free interest rate, r, continuously compounded. Note that a rate of 5% should be entered as 0.05.
Constraint: R≥0.0 and abs R-Q>10×eps×max abs R,1, where eps=X02AJF, the machine precision.
9:   Q – REAL (KIND=nag_wp)Input
On entry: the annual continuous yield rate. Note that a rate of 8% should be entered as 0.08.
Constraint: Q≥0.0 and abs R-Q>10×eps×max abs R,1, where eps=X02AJF, the machine precision.
10:   P LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: P ij contains P ij, the option price evaluated for the minimum or maximum observed price Smin i or Smax i at expiry Tj for i=1,2,…,M and j=1,2,…,N.
11:   LDP – INTEGERInput
On entry: the first dimension of the arrays P, DELTA, GAMMA, VEGA, THETA, RHO, CRHO, VANNA, CHARM, SPEED, COLOUR, ZOMMA and VOMMA as declared in the (sub)program from which S30BBF is called.
Constraint: LDP≥M.
12:   DELTA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: the leading M×N part of the array DELTA contains the sensitivity, ∂P∂S, of the option price to change in the price of the underlying asset.
13:   GAMMA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: the leading M×N part of the array GAMMA contains the sensitivity, ∂2 P∂S 2, of DELTA to change in the price of the underlying asset.
14:   VEGA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: VEGA ij, contains the first-order Greek measuring the sensitivity of the option price P ij to change in the volatility of the underlying asset, i.e., ∂P ij ∂σ , for i=1,2,…,M and j=1,2,…,N.
15:   THETA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: THETA ij, contains the first-order Greek measuring the sensitivity of the option price P ij to change in time, i.e., - ∂P ij ∂T , for i=1,2,…,M and j=1,2,…,N, where b=r-q.
16:   RHO LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: RHO ij, contains the first-order Greek measuring the sensitivity of the option price P ij to change in the annual risk-free interest rate, i.e., - ∂P ij ∂r , for i=1,2,…,M and j=1,2,…,N.
17:   CRHO LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: CRHO ij, contains the first-order Greek measuring the sensitivity of the option price P ij to change in the annual cost of carry rate, i.e., - ∂P ij ∂b , for i=1,2,…,M and j=1,2,…,N, where b=r-q.
18:   VANNA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: VANNA ij, contains the second-order Greek measuring the sensitivity of the first-order Greek Δ ij to change in the volatility of the asset price, i.e., - ∂Δ ij ∂T = - ∂2 P ij ∂S∂σ , for i=1,2,…,M and j=1,2,…,N.
19:   CHARM LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: CHARM ij, contains the second-order Greek measuring the sensitivity of the first-order Greek Δ ij to change in the time, i.e., - ∂Δ ij ∂T = - ∂2 P ij ∂S∂T , for i=1,2,…,M and j=1,2,…,N.
20:   SPEED LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: SPEED ij, contains the third-order Greek measuring the sensitivity of the second-order Greek Γ ij to change in the price of the underlying asset, i.e., - ∂Γ ij ∂S = - ∂3 P ij ∂S 3 , for i=1,2,…,M and j=1,2,…,N.
21:   COLOUR LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: COLOUR ij, contains the third-order Greek measuring the sensitivity of the second-order Greek Γ ij to change in the time, i.e., - ∂Γ ij ∂T = - ∂3 P ij ∂S∂T , for i=1,2,…,M and j=1,2,…,N.
22:   ZOMMA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: ZOMMA ij, contains the third-order Greek measuring the sensitivity of the second-order Greek Γ ij to change in the volatility of the underlying asset, i.e., - ∂Γ ij ∂σ = - ∂3 P ij ∂S 2∂σ , for i=1,2,…,M and j=1,2,…,N.
23:   VOMMA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: VOMMA ij, contains the second-order Greek measuring the sensitivity of the first-order Greek Δ ij to change in the volatility of the underlying asset, i.e., - ∂Δ ij ∂σ = - ∂2 P ij ∂σ 2 , for i=1,2,…,M and j=1,2,…,N.
24:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, CALPUT=value was an illegal value.
IFAIL=2
On entry, M=value.
Constraint: M≥1.
IFAIL=3
On entry, N=value.
Constraint: N≥1.
IFAIL=4
On entry, SM value=value.
Constraint: value≤SM i≤value for all i.
On entry with a call option, SM value=value.
Constraint: for call options, SM i≤value for all i.
On entry with a put option, SM value=value.
Constraint: for put options, SM i≥value for all i.
IFAIL=5
On entry, S=value.
Constraint: S≥value and S≤value.
IFAIL=6
On entry, T value=value.
Constraint: T i≥value for all i.
IFAIL=7
On entry, SIGMA=value.
Constraint: SIGMA>0.0.
IFAIL=8
On entry, R=value.
Constraint: R≥0.0.
IFAIL=9
On entry, Q=value.
Constraint: Q≥0.0.
IFAIL=11
On entry, LDP=value and M=value.
Constraint: LDP≥M.
IFAIL=12
On entry, R=value and Q=value.
Constraint: R-Q>10×eps×max R,1, where eps is the machine precision.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The accuracy of the output is dependent on the accuracy of the cumulative Normal distribution function, Φ. This is evaluated using a rational Chebyshev expansion, chosen so that the maximum relative error in the expansion is of the order of the machine precision (see S15ABF and S15ADF). An accuracy close to machine precision can generally be expected.

8 Parallelism and Performance

S30BBF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

None.

10 Example

This example computes the price of a floating-strike lookback put with a time to expiry of 6 months and a stock price of 87. The maximum price observed so far is 100. The risk-free interest rate is 6% per year and the volatility is 30% per year with an annual dividend return of 4%.

10.1 Program Text

Program Text (s30bbfe.f90)

10.2 Program Data

Program Data (s30bbfe.d)

10.3 Program Results

Program Results (s30bbfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S30CAF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S30CAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S30CAF computes the price of a binary or digital cash-or-nothing option.

2 Specification

SUBROUTINE S30CAF ( CALPUT, M, N, X, S, K, T, SIGMA, R, Q, P, LDP, IFAIL)
INTEGER | M, N, LDP, IFAIL
REAL (KIND=nag_wp) | X(M), S, K, T(N), SIGMA, R, Q, P(LDP,N)
CHARACTER(1) | CALPUT

3 Description

S30CAF computes the price of a binary or digital cash-or-nothing option which pays a fixed amount, K, at expiration if the option is in-the-money (see Section 2.4 in the S Chapter Introduction). For a strike price, X, underlying asset price, S, and time to expiry, T, the payoff is therefore K, if S>X for a call or S<X for a put. Nothing is paid out when this condition is not met.
The price of a call with volatility, σ, risk-free interest rate, r, and annualised dividend yield, q, is
Pcall = K e-rT Φ d 2
and for a put,
Pput = K e-rT Φ-d 2
where Φ is the cumulative Normal distribution function,
Φ x = 1 2 π ∫ -∞ x -y 2/2 dy ,
and
d 2 = ln S/X + r-q - σ 2 / 2 T σ⁢T .
The option price P ij=P X=Xi,T=Tj is computed for each strike price in a set Xi, i=1,2,…,m, and for each expiry time in a set Tj, j=1,2,…,n.

4 References

Reiner E and Rubinstein M (1991) Unscrambling the binary code Risk 4

5 Arguments

1:   CALPUT – CHARACTER(1)Input
On entry: determines whether the option is a call or a put.
CALPUT='C'
A call; the holder has a right to buy.
CALPUT='P'
A put; the holder has a right to sell.
Constraint: CALPUT='C' or 'P'.
2:   M – INTEGERInput
On entry: the number of strike prices to be used.
Constraint: M≥1.
3:   N – INTEGERInput
On entry: the number of times to expiry to be used.
Constraint: N≥1.
4:   X M – REAL (KIND=nag_wp) arrayInput
On entry: X i must contain Xi, the ith strike price, for i=1,2,…,M.
Constraint: X i≥z ​ and ​ X i ≤ 1 / z , where z = X02AMF , the safe range parameter, for i=1,2,…,M.
5:   S – REAL (KIND=nag_wp)Input
On entry: S, the price of the underlying asset.
Constraint: S≥z ​ and ​S≤1.0/z, where z=X02AMF, the safe range parameter.
6:   K – REAL (KIND=nag_wp)Input
On entry: the amount, K, to be paid at expiration if the option is in-the-money, i.e., if S>X i when CALPUT='C', or if S<X i when CALPUT='P', for i=1,2,…,m.
Constraint: K≥0.0.
7:   T N – REAL (KIND=nag_wp) arrayInput
On entry: T i must contain Ti, the ith time, in years, to expiry, for i=1,2,…,N.
Constraint: T i≥z, where z = X02AMF , the safe range parameter, for i=1,2,…,N.
8:   SIGMA – REAL (KIND=nag_wp)Input
On entry: σ, the volatility of the underlying asset. Note that a rate of 15% should be entered as 0.15.
Constraint: SIGMA>0.0.
9:   R – REAL (KIND=nag_wp)Input
On entry: r, the annual risk-free interest rate, continuously compounded. Note that a rate of 5% should be entered as 0.05.
Constraint: R≥0.0.
10:   Q – REAL (KIND=nag_wp)Input
On entry: q, the annual continuous yield rate. Note that a rate of 8% should be entered as 0.08.
Constraint: Q≥0.0.
11:   P LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: P ij contains P ij, the option price evaluated for the strike price Xi at expiry Tj for i=1,2,…,M and j=1,2,…,N.
12:   LDP – INTEGERInput
On entry: the first dimension of the array P as declared in the (sub)program from which S30CAF is called.
Constraint: LDP≥M.
13:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, CALPUT=value was an illegal value.
IFAIL=2
On entry, M=value.
Constraint: M≥1.
IFAIL=3
On entry, N=value.
Constraint: N≥1.
IFAIL=4
On entry, X value=value.
Constraint: X i≥value and X i≤value.
IFAIL=5
On entry, S=value.
Constraint: S≥value and S≤value.
IFAIL=6
On entry, K=value.
Constraint: K≥0.0.
IFAIL=7
On entry, T value=value.
Constraint: T i≥value.
IFAIL=8
On entry, SIGMA=value.
Constraint: SIGMA>0.0.
IFAIL=9
On entry, R=value.
Constraint: R≥0.0.
IFAIL=10
On entry, Q=value.
Constraint: Q≥0.0.
IFAIL=12
On entry, LDP=value and M=value.
Constraint: LDP≥M.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The accuracy of the output is dependent on the accuracy of the cumulative Normal distribution function, Φ. This is evaluated using a rational Chebyshev expansion, chosen so that the maximum relative error in the expansion is of the order of the machine precision (see S15ABF and S15ADF). An accuracy close to machine precision can generally be expected.

8 Parallelism and Performance

S30CAF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

None.

10 Example

This example computes the price of a cash-or-nothing put with a time to expiry of 0.75 years, a stock price of 100 and a strike price of 80. The risk-free interest rate is 6% per year and the volatility is 35% per year. If the option is in-the-money at expiration, i.e., if S>X, the payoff is 10.

10.1 Program Text

Program Text (s30cafe.f90)

10.2 Program Data

Program Data (s30cafe.d)

10.3 Program Results

Program Results (s30cafe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S30CBF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S30CBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S30CBF computes the price of a binary or digital cash-or-nothing option together with its sensitivities (Greeks).

2 Specification

SUBROUTINE S30CBF ( CALPUT, M, N, X, S, K, T, SIGMA, R, Q, P, LDP, DELTA, GAMMA, VEGA, THETA, RHO, CRHO, VANNA, CHARM, SPEED, COLOUR, ZOMMA, VOMMA, IFAIL)
INTEGER | M, N, LDP, IFAIL
REAL (KIND=nag_wp) | X(M), S, K, T(N), SIGMA, R, Q, P(LDP,N), DELTA(LDP,N), GAMMA(LDP,N), VEGA(LDP,N), THETA(LDP,N), RHO(LDP,N), CRHO(LDP,N), VANNA(LDP,N), CHARM(LDP,N), SPEED(LDP,N), COLOUR(LDP,N), ZOMMA(LDP,N), VOMMA(LDP,N)
CHARACTER(1) | CALPUT

3 Description

S30CBF computes the price of a binary or digital cash-or-nothing option, together with the Greeks or sensitivities, which are the partial derivatives of the option price with respect to certain of the other input parameters. This option pays a fixed amount, K, at expiration if the option is in-the-money (see Section 2.4 in the S Chapter Introduction). For a strike price, X, underlying asset price, S, and time to expiry, T, the payoff is therefore K, if S>X for a call or S<X for a put. Nothing is paid out when this condition is not met.
The price of a call with volatility, σ, risk-free interest rate, r, and annualised dividend yield, q, is
Pcall = K e-rT Φ d 2
and for a put,
Pput = K e-rT Φ-d 2
where Φ is the cumulative Normal distribution function,
Φ x = 1 2 π ∫ -∞ x exp -y 2/2 dy ,
and
d 2 = ln S/X + r-q- σ 2 / 2 T σ⁢T .
The option price P ij=P X=Xi,T=Tj is computed for each strike price in a set Xi, i=1,2,…,m, and for each expiry time in a set Tj, j=1,2,…,n.

4 References

Reiner E and Rubinstein M (1991) Unscrambling the binary code Risk 4

5 Arguments

1:   CALPUT – CHARACTER(1)Input
On entry: determines whether the option is a call or a put.
CALPUT='C'
A call; the holder has a right to buy.
CALPUT='P'
A put; the holder has a right to sell.
Constraint: CALPUT='C' or 'P'.
2:   M – INTEGERInput
On entry: the number of strike prices to be used.
Constraint: M≥1.
3:   N – INTEGERInput
On entry: the number of times to expiry to be used.
Constraint: N≥1.
4:   X M – REAL (KIND=nag_wp) arrayInput
On entry: X i must contain Xi, the ith strike price, for i=1,2,…,M.
Constraint: X i≥z ​ and ​ X i ≤ 1 / z , where z = X02AMF , the safe range parameter, for i=1,2,…,M.
5:   S – REAL (KIND=nag_wp)Input
On entry: S, the price of the underlying asset.
Constraint: S≥z ​ and ​S≤1.0/z, where z=X02AMF, the safe range parameter.
6:   K – REAL (KIND=nag_wp)Input
On entry: the amount, K, to be paid at expiration if the option is in-the-money, i.e., if S>X i when CALPUT='C', or if S<X i when CALPUT='P', for i=1,2,…,m.
Constraint: K≥0.0.
7:   T N – REAL (KIND=nag_wp) arrayInput
On entry: T i must contain Ti, the ith time, in years, to expiry, for i=1,2,…,N.
Constraint: T i≥z, where z = X02AMF , the safe range parameter, for i=1,2,…,N.
8:   SIGMA – REAL (KIND=nag_wp)Input
On entry: σ, the volatility of the underlying asset. Note that a rate of 15% should be entered as 0.15.
Constraint: SIGMA>0.0.
9:   R – REAL (KIND=nag_wp)Input
On entry: r, the annual risk-free interest rate, continuously compounded. Note that a rate of 5% should be entered as 0.05.
Constraint: R≥0.0.
10:   Q – REAL (KIND=nag_wp)Input
On entry: q, the annual continuous yield rate. Note that a rate of 8% should be entered as 0.08.
Constraint: Q≥0.0.
11:   P LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: P ij contains P ij, the option price evaluated for the strike price Xi at expiry Tj for i=1,2,…,M and j=1,2,…,N.
12:   LDP – INTEGERInput
On entry: the first dimension of the arrays P, DELTA, GAMMA, VEGA, THETA, RHO, CRHO, VANNA, CHARM, SPEED, COLOUR, ZOMMA and VOMMA as declared in the (sub)program from which S30CBF is called.
Constraint: LDP≥M.
13:   DELTA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: the leading M×N part of the array DELTA contains the sensitivity, ∂P∂S, of the option price to change in the price of the underlying asset.
14:   GAMMA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: the leading M×N part of the array GAMMA contains the sensitivity, ∂2 P∂S 2, of DELTA to change in the price of the underlying asset.
15:   VEGA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: VEGA ij, contains the first-order Greek measuring the sensitivity of the option price P ij to change in the volatility of the underlying asset, i.e., ∂P ij ∂σ , for i=1,2,…,M and j=1,2,…,N.
16:   THETA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: THETA ij, contains the first-order Greek measuring the sensitivity of the option price P ij to change in time, i.e., - ∂P ij ∂T , for i=1,2,…,M and j=1,2,…,N, where b=r-q.
17:   RHO LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: RHO ij, contains the first-order Greek measuring the sensitivity of the option price P ij to change in the annual risk-free interest rate, i.e., - ∂P ij ∂r , for i=1,2,…,M and j=1,2,…,N.
18:   CRHO LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: CRHO ij, contains the first-order Greek measuring the sensitivity of the option price P ij to change in the annual cost of carry rate, i.e., - ∂P ij ∂b , for i=1,2,…,M and j=1,2,…,N, where b=r-q.
19:   VANNA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: VANNA ij, contains the second-order Greek measuring the sensitivity of the first-order Greek Δ ij to change in the volatility of the asset price, i.e., - ∂Δ ij ∂T = - ∂2 P ij ∂S∂σ , for i=1,2,…,M and j=1,2,…,N.
20:   CHARM LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: CHARM ij, contains the second-order Greek measuring the sensitivity of the first-order Greek Δ ij to change in the time, i.e., - ∂Δ ij ∂T = - ∂2 P ij ∂S∂T , for i=1,2,…,M and j=1,2,…,N.
21:   SPEED LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: SPEED ij, contains the third-order Greek measuring the sensitivity of the second-order Greek Γ ij to change in the price of the underlying asset, i.e., - ∂Γ ij ∂S = - ∂3 P ij ∂S 3 , for i=1,2,…,M and j=1,2,…,N.
22:   COLOUR LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: COLOUR ij, contains the third-order Greek measuring the sensitivity of the second-order Greek Γ ij to change in the time, i.e., - ∂Γ ij ∂T = - ∂3 P ij ∂S∂T , for i=1,2,…,M and j=1,2,…,N.
23:   ZOMMA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: ZOMMA ij, contains the third-order Greek measuring the sensitivity of the second-order Greek Γ ij to change in the volatility of the underlying asset, i.e., - ∂Γ ij ∂σ = - ∂3 P ij ∂S 2∂σ , for i=1,2,…,M and j=1,2,…,N.
24:   VOMMA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: VOMMA ij, contains the second-order Greek measuring the sensitivity of the first-order Greek Δ ij to change in the volatility of the underlying asset, i.e., - ∂Δ ij ∂σ = - ∂2 P ij ∂σ 2 , for i=1,2,…,M and j=1,2,…,N.
25:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, CALPUT=value was an illegal value.
IFAIL=2
On entry, M=value.
Constraint: M≥1.
IFAIL=3
On entry, N=value.
Constraint: N≥1.
IFAIL=4
On entry, X value=value.
Constraint: X i≥value and X i≤value.
IFAIL=5
On entry, S=value.
Constraint: S≥value and S≤value.
IFAIL=6
On entry, K=value.
Constraint: K≥0.0.
IFAIL=7
On entry, T value=value.
Constraint: T i≥value.
IFAIL=8
On entry, SIGMA=value.
Constraint: SIGMA>0.0.
IFAIL=9
On entry, R=value.
Constraint: R≥0.0.
IFAIL=10
On entry, Q=value.
Constraint: Q≥0.0.
IFAIL=12
On entry, LDP=value and M=value.
Constraint: LDP≥M.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The accuracy of the output is dependent on the accuracy of the cumulative Normal distribution function, Φ. This is evaluated using a rational Chebyshev expansion, chosen so that the maximum relative error in the expansion is of the order of the machine precision (see S15ABF and S15ADF). An accuracy close to machine precision can generally be expected.

8 Parallelism and Performance

S30CBF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

None.

10 Example

This example computes the price of a cash-or-nothing call with a time to expiry of 0.75 years, a stock price of 110 and a strike price of 87. The risk-free interest rate is 5% per year, there is an annual dividend return of 4% and the volatility is 35% per year. If the option is in-the-money at expiration, i.e., if S>X, the payoff is 5.

10.1 Program Text

Program Text (s30cbfe.f90)

10.2 Program Data

Program Data (s30cbfe.d)

10.3 Program Results

Program Results (s30cbfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S30CCF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S30CCF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S30CCF computes the price of a binary or digital asset-or-nothing option.

2 Specification

SUBROUTINE S30CCF ( CALPUT, M, N, X, S, T, SIGMA, R, Q, P, LDP, IFAIL)
INTEGER | M, N, LDP, IFAIL
REAL (KIND=nag_wp) | X(M), S, T(N), SIGMA, R, Q, P(LDP,N)
CHARACTER(1) | CALPUT

3 Description

S30CCF computes the price of a binary or digital asset-or-nothing option which pays the underlying asset itself, S, at expiration if the option is in-the-money (see Section 2.4 in the S Chapter Introduction). For a strike price, X, underlying asset price, S, and time to expiry, T, the payoff is therefore S, if S>X for a call or S<X for a put. Nothing is paid out when this condition is not met.
The price of a call with volatility, σ, risk-free interest rate, r, and annualised dividend yield, q, is
Pcall = S e-qT Φ d 1
and for a put,
Pput = S e-qT Φ-d 1
where Φ is the cumulative Normal distribution function,
Φ x = 1 2 π ∫ -∞ x exp -y 2/2 dy ,
and
d 1 = ln S/X + r-q + σ 2 / 2 T σ⁢T .
The option price P ij=P X=Xi,T=Tj is computed for each strike price in a set Xi, i=1,2,…,m, and for each expiry time in a set Tj, j=1,2,…,n.

4 References

Reiner E and Rubinstein M (1991) Unscrambling the binary code Risk 4

5 Arguments

1:   CALPUT – CHARACTER(1)Input
On entry: determines whether the option is a call or a put.
CALPUT='C'
A call; the holder has a right to buy.
CALPUT='P'
A put; the holder has a right to sell.
Constraint: CALPUT='C' or 'P'.
2:   M – INTEGERInput
On entry: the number of strike prices to be used.
Constraint: M≥1.
3:   N – INTEGERInput
On entry: the number of times to expiry to be used.
Constraint: N≥1.
4:   X M – REAL (KIND=nag_wp) arrayInput
On entry: X i must contain Xi, the ith strike price, for i=1,2,…,M.
Constraint: X i≥z ​ and ​ X i ≤ 1 / z , where z = X02AMF , the safe range parameter, for i=1,2,…,M.
5:   S – REAL (KIND=nag_wp)Input
On entry: S, the price of the underlying asset.
Constraint: S≥z ​ and ​S≤1.0/z, where z=X02AMF, the safe range parameter.
6:   T N – REAL (KIND=nag_wp) arrayInput
On entry: T i must contain Ti, the ith time, in years, to expiry, for i=1,2,…,N.
Constraint: T i≥z, where z = X02AMF , the safe range parameter, for i=1,2,…,N.
7:   SIGMA – REAL (KIND=nag_wp)Input
On entry: σ, the volatility of the underlying asset. Note that a rate of 15% should be entered as 0.15.
Constraint: SIGMA>0.0.
8:   R – REAL (KIND=nag_wp)Input
On entry: r, the annual risk-free interest rate, continuously compounded. Note that a rate of 5% should be entered as 0.05.
Constraint: R≥0.0.
9:   Q – REAL (KIND=nag_wp)Input
On entry: q, the annual continuous yield rate. Note that a rate of 8% should be entered as 0.08.
Constraint: Q≥0.0.
10:   P LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: P ij contains P ij, the option price evaluated for the strike price Xi at expiry Tj for i=1,2,…,M and j=1,2,…,N.
11:   LDP – INTEGERInput
On entry: the first dimension of the array P as declared in the (sub)program from which S30CCF is called.
Constraint: LDP≥M.
12:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, CALPUT=value was an illegal value.
IFAIL=2
On entry, M=value.
Constraint: M≥1.
IFAIL=3
On entry, N=value.
Constraint: N≥1.
IFAIL=4
On entry, X value=value.
Constraint: X i≥value and X i≤value.
IFAIL=5
On entry, S=value.
Constraint: S≥value and S≤value.
IFAIL=6
On entry, T value=value.
Constraint: T i≥value.
IFAIL=7
On entry, SIGMA=value.
Constraint: SIGMA>0.0.
IFAIL=8
On entry, R=value.
Constraint: R≥0.0.
IFAIL=9
On entry, Q=value.
Constraint: Q≥0.0.
IFAIL=11
On entry, LDP=value and M=value.
Constraint: LDP≥M.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The accuracy of the output is dependent on the accuracy of the cumulative Normal distribution function, Φ. This is evaluated using a rational Chebyshev expansion, chosen so that the maximum relative error in the expansion is of the order of the machine precision (see S15ABF and S15ADF). An accuracy close to machine precision can generally be expected.

8 Parallelism and Performance

S30CCF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

None.

10 Example

This example computes the price of an asset-or-nothing put with a time to expiry of 0.5 years, a stock price of 70 and a strike price of 65. The risk-free interest rate is 7% per year, there is an annual dividend return of 5% and the volatility is 27% per year.

10.1 Program Text

Program Text (s30ccfe.f90)

10.2 Program Data

Program Data (s30ccfe.d)

10.3 Program Results

Program Results (s30ccfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S30CDF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S30CDF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S30CDF computes the price of a binary or digital asset-or-nothing option together with its sensitivities (Greeks).

2 Specification

SUBROUTINE S30CDF ( CALPUT, M, N, X, S, T, SIGMA, R, Q, P, LDP, DELTA, GAMMA, VEGA, THETA, RHO, CRHO, VANNA, CHARM, SPEED, COLOUR, ZOMMA, VOMMA, IFAIL)
INTEGER | M, N, LDP, IFAIL
REAL (KIND=nag_wp) | X(M), S, T(N), SIGMA, R, Q, P(LDP,N), DELTA(LDP,N), GAMMA(LDP,N), VEGA(LDP,N), THETA(LDP,N), RHO(LDP,N), CRHO(LDP,N), VANNA(LDP,N), CHARM(LDP,N), SPEED(LDP,N), COLOUR(LDP,N), ZOMMA(LDP,N), VOMMA(LDP,N)
CHARACTER(1) | CALPUT

3 Description

S30CDF computes the price of a binary or digital asset-or-nothing option, together with the Greeks or sensitivities, which are the partial derivatives of the option price with respect to certain of the other input parameters. This option pays the underlying asset itself, S, at expiration if the option is in-the-money (see Section 2.4 in the S Chapter Introduction). For a strike price, X, underlying asset price, S, and time to expiry, T, the payoff is therefore S, if S>X for a call or S<X for a put. Nothing is paid out when this condition is not met.
The price of a call with volatility, σ, risk-free interest rate, r, and annualised dividend yield, q, is
Pcall = S e-qT Φ d 1
and for a put,
Pput = S e-qT Φ-d 1
where Φ is the cumulative Normal distribution function,
Φ x = 1 2 π ∫ -∞ x exp -y 2/2 dy ,
and
d 1 = ln S/X + r-q + σ 2 / 2 T σ⁢T .
The option price P ij=P X=Xi,T=Tj is computed for each strike price in a set Xi, i=1,2,…,m, and for each expiry time in a set Tj, j=1,2,…,n.

4 References

Reiner E and Rubinstein M (1991) Unscrambling the binary code Risk 4

5 Arguments

1:   CALPUT – CHARACTER(1)Input
On entry: determines whether the option is a call or a put.
CALPUT='C'
A call; the holder has a right to buy.
CALPUT='P'
A put; the holder has a right to sell.
Constraint: CALPUT='C' or 'P'.
2:   M – INTEGERInput
On entry: the number of strike prices to be used.
Constraint: M≥1.
3:   N – INTEGERInput
On entry: the number of times to expiry to be used.
Constraint: N≥1.
4:   X M – REAL (KIND=nag_wp) arrayInput
On entry: X i must contain Xi, the ith strike price, for i=1,2,…,M.
Constraint: X i≥z ​ and ​ X i ≤ 1 / z , where z = X02AMF , the safe range parameter, for i=1,2,…,M.
5:   S – REAL (KIND=nag_wp)Input
On entry: S, the price of the underlying asset.
Constraint: S≥z ​ and ​S≤1.0/z, where z=X02AMF, the safe range parameter.
6:   T N – REAL (KIND=nag_wp) arrayInput
On entry: T i must contain Ti, the ith time, in years, to expiry, for i=1,2,…,N.
Constraint: T i≥z, where z = X02AMF , the safe range parameter, for i=1,2,…,N.
7:   SIGMA – REAL (KIND=nag_wp)Input
On entry: σ, the volatility of the underlying asset. Note that a rate of 15% should be entered as 0.15.
Constraint: SIGMA>0.0.
8:   R – REAL (KIND=nag_wp)Input
On entry: r, the annual risk-free interest rate, continuously compounded. Note that a rate of 5% should be entered as 0.05.
Constraint: R≥0.0.
9:   Q – REAL (KIND=nag_wp)Input
On entry: q, the annual continuous yield rate. Note that a rate of 8% should be entered as 0.08.
Constraint: Q≥0.0.
10:   P LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: P ij contains P ij, the option price evaluated for the strike price Xi at expiry Tj for i=1,2,…,M and j=1,2,…,N.
11:   LDP – INTEGERInput
On entry: the first dimension of the arrays P, DELTA, GAMMA, VEGA, THETA, RHO, CRHO, VANNA, CHARM, SPEED, COLOUR, ZOMMA and VOMMA as declared in the (sub)program from which S30CDF is called.
Constraint: LDP≥M.
12:   DELTA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: the leading M×N part of the array DELTA contains the sensitivity, ∂P∂S, of the option price to change in the price of the underlying asset.
13:   GAMMA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: the leading M×N part of the array GAMMA contains the sensitivity, ∂2 P∂S 2, of DELTA to change in the price of the underlying asset.
14:   VEGA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: VEGA ij, contains the first-order Greek measuring the sensitivity of the option price P ij to change in the volatility of the underlying asset, i.e., ∂P ij ∂σ , for i=1,2,…,M and j=1,2,…,N.
15:   THETA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: THETA ij, contains the first-order Greek measuring the sensitivity of the option price P ij to change in time, i.e., - ∂P ij ∂T , for i=1,2,…,M and j=1,2,…,N, where b=r-q.
16:   RHO LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: RHO ij, contains the first-order Greek measuring the sensitivity of the option price P ij to change in the annual risk-free interest rate, i.e., - ∂P ij ∂r , for i=1,2,…,M and j=1,2,…,N.
17:   CRHO LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: CRHO ij, contains the first-order Greek measuring the sensitivity of the option price P ij to change in the annual cost of carry rate, i.e., - ∂P ij ∂b , for i=1,2,…,M and j=1,2,…,N, where b=r-q.
18:   VANNA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: VANNA ij, contains the second-order Greek measuring the sensitivity of the first-order Greek Δ ij to change in the volatility of the asset price, i.e., - ∂Δ ij ∂T = - ∂2 P ij ∂S∂σ , for i=1,2,…,M and j=1,2,…,N.
19:   CHARM LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: CHARM ij, contains the second-order Greek measuring the sensitivity of the first-order Greek Δ ij to change in the time, i.e., - ∂Δ ij ∂T = - ∂2 P ij ∂S∂T , for i=1,2,…,M and j=1,2,…,N.
20:   SPEED LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: SPEED ij, contains the third-order Greek measuring the sensitivity of the second-order Greek Γ ij to change in the price of the underlying asset, i.e., - ∂Γ ij ∂S = - ∂3 P ij ∂S 3 , for i=1,2,…,M and j=1,2,…,N.
21:   COLOUR LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: COLOUR ij, contains the third-order Greek measuring the sensitivity of the second-order Greek Γ ij to change in the time, i.e., - ∂Γ ij ∂T = - ∂3 P ij ∂S∂T , for i=1,2,…,M and j=1,2,…,N.
22:   ZOMMA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: ZOMMA ij, contains the third-order Greek measuring the sensitivity of the second-order Greek Γ ij to change in the volatility of the underlying asset, i.e., - ∂Γ ij ∂σ = - ∂3 P ij ∂S 2∂σ , for i=1,2,…,M and j=1,2,…,N.
23:   VOMMA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: VOMMA ij, contains the second-order Greek measuring the sensitivity of the first-order Greek Δ ij to change in the volatility of the underlying asset, i.e., - ∂Δ ij ∂σ = - ∂2 P ij ∂σ 2 , for i=1,2,…,M and j=1,2,…,N.
24:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, CALPUT=value was an illegal value.
IFAIL=2
On entry, M=value.
Constraint: M≥1.
IFAIL=3
On entry, N=value.
Constraint: N≥1.
IFAIL=4
On entry, X value=value.
Constraint: X i≥value and X i≤value.
IFAIL=5
On entry, S=value.
Constraint: S≥value and S≤value.
IFAIL=6
On entry, T value=value.
Constraint: T i≥value.
IFAIL=7
On entry, SIGMA=value.
Constraint: SIGMA>0.0.
IFAIL=8
On entry, R=value.
Constraint: R≥0.0.
IFAIL=9
On entry, Q=value.
Constraint: Q≥0.0.
IFAIL=11
On entry, LDP=value and M=value.
Constraint: LDP≥M.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The accuracy of the output is dependent on the accuracy of the cumulative Normal distribution function, Φ. This is evaluated using a rational Chebyshev expansion, chosen so that the maximum relative error in the expansion is of the order of the machine precision (see S15ABF and S15ADF). An accuracy close to machine precision can generally be expected.

8 Parallelism and Performance

S30CDF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

None.

10 Example

This example computes the price of an asset-or-nothing put with a time to expiry of 292 days, a stock price of 70 and a strike price of 65. The risk-free interest rate is 5% per year, there is an annual dividend return of 3% and the volatility is 15% per year.

10.1 Program Text

Program Text (s30cdfe.f90)

10.2 Program Data

Program Data (s30cdfe.d)

10.3 Program Results

Program Results (s30cdfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S30FAF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S30FAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S30FAF computes the price of a standard barrier option.

2 Specification

SUBROUTINE S30FAF ( CALPUT, TYPE, M, N, X, S, H, K, T, SIGMA, R, Q, P, LDP, IFAIL)
INTEGER | M, N, LDP, IFAIL
REAL (KIND=nag_wp) | X(M), S, H, K, T(N), SIGMA, R, Q, P(LDP,N)
CHARACTER(1) | CALPUT
CHARACTER(2) | TYPE

3 Description

S30FAF computes the price of a standard barrier option, where the exercise, for a given strike price, X, depends on the underlying asset price, S, reaching or crossing a specified barrier level, H. Barrier options of type In only become active (are knocked in) if the underlying asset price attains the pre-determined barrier level during the lifetime of the contract. Those of type Out start active and are knocked out if the underlying asset price attains the barrier level during the lifetime of the contract. A cash rebate, K, may be paid if the option is inactive at expiration. The option may also be described as Up (the underlying price starts below the barrier level) or Down (the underlying price starts above the barrier level). This gives the following options which can be specified as put or call contracts.
Down-and-In: the option starts inactive with the underlying asset price above the barrier level. It is knocked in if the underlying price moves down to hit the barrier level before expiration.
Down-and-Out: the option starts active with the underlying asset price above the barrier level. It is knocked out if the underlying price moves down to hit the barrier level before expiration.
Up-and-In: the option starts inactive with the underlying asset price below the barrier level. It is knocked in if the underlying price moves up to hit the barrier level before expiration.
Up-and-Out: the option starts active with the underlying asset price below the barrier level. It is knocked out if the underlying price moves up to hit the barrier level before expiration.
The payoff is max S-X,0 for a call or max X-S,0 for a put, if the option is active at expiration, otherwise it may pay a pre-specified cash rebate, K. Following Haug (2007), the prices of the various standard barrier options can be written as shown below. The volatility, σ, risk-free interest rate, r, and annualised dividend yield, q, are constants. The integer parameters, j and k, take the values ±1, depending on the type of barrier.
A = j S e-qT Φ j x 1 - j X e-rT Φ j x 1 - σ⁢T B = j S e-qT Φ j x 2 - j X e-rT Φ j x 2 - σ⁢T C = j S e-qT HS 2 μ+1 Φ k y 1 - j X e-rT HS 2 μ Φ k y 1 - σ⁢T D = j S e-qT HS 2 μ+1 Φ k y 2 - j X e-rT HS 2 μ Φ k y 2 - σ⁢T E = K e-rT Φ k x 2 - σ⁢T - HS 2 μ Φ k y 2 - σ⁢T F = K HS μ+λ Φ kz + HS μ-λ Φ k z-σ⁢T
with
x 1 = ln S/X σ⁢T + 1+μ σ⁢T x 2 = ln S/H σ⁢T + 1+μ σ⁢T y 1 = ln H 2 / SX σ⁢T + 1+μ σ⁢T y 2 = ln H/S σ⁢T + 1+μ σ⁢T z = ln H/S σ⁢T + λσ⁢T μ = r-q-σ 2 / 2 σ 2 λ = μ 2 + 2 r σ 2
and where Φ denotes the cumulative Normal distribution function,
Φ x = 1 2 π ∫ -∞ x exp -y 2/2 dy .
Down-and-In (S>H):
  • When X≥H, with j=k=1,
    Pcall = C + E
    and with j=-1, k=1
    Pput = B - C + D + E
    When X<H, with j=k=1
    Pcall = A - B + D + E
    and with j=-1, k=1
    Pput = A + E .
Down-and-Out (S>H):
  • When X≥H, with j=k=1,
    Pcall = A-C + F
    and with j=-1, k=1
    Pput = A - B + C - D + F
    When X<H, with j=k=1,
    Pcall = B - D + F
    and with j=-1, k=1
    Pput = F .
Up-and-In (S<H):
  • When X≥H, with j=1, k=-1,
    Pcall = A + E
    and with j=k=-1,
    Pput = A - B + D + E
    When X<H, with j=1, k=-1,
    Pcall = B - C + D + E
    and with j=k=-1,
    Pput = C + E .
Up-and-Out (S<H):
  • When X≥H, with j=1, k=-1,
    Pcall = F
    and with j=k=-1,
    Pput = B - D + F
    When X<H, with j=1, k=-1,
    Pcall = A - B + C - D + F
    and with j=k=-1,
    Pput = A - C + F .
The option price P ij=P X=Xi,T=Tj is computed for each strike price in a set Xi, i=1,2,…,m, and for each expiry time in a set Tj, j=1,2,…,n.

4 References

Haug E G (2007) The Complete Guide to Option Pricing Formulas (2nd Edition) McGraw-Hill

5 Arguments

1:   CALPUT – CHARACTER(1)Input
On entry: determines whether the option is a call or a put.
CALPUT='C'
A call; the holder has a right to buy.
CALPUT='P'
A put; the holder has a right to sell.
Constraint: CALPUT='C' or 'P'.
2:   TYPE – CHARACTER(2)Input
On entry: indicates the barrier type as In or Out and its relation to the price of the underlying asset as Up or Down.
TYPE='DI'
Down-and-In.
TYPE='DO'
Down-and-Out.
TYPE='UI'
Up-and-In.
TYPE='UO'
Up-and-Out.
Constraint: TYPE='DI', 'DO', 'UI' or 'UO'.
3:   M – INTEGERInput
On entry: the number of strike prices to be used.
Constraint: M≥1.
4:   N – INTEGERInput
On entry: the number of times to expiry to be used.
Constraint: N≥1.
5:   X M – REAL (KIND=nag_wp) arrayInput
On entry: X i must contain Xi, the ith strike price, for i=1,2,…,M.
Constraint: X i≥z ​ and ​ X i ≤ 1 / z , where z = X02AMF , the safe range parameter, for i=1,2,…,M.
6:   S – REAL (KIND=nag_wp)Input
On entry: S, the price of the underlying asset.
Constraint: S≥z ​ and ​S≤1.0/z, where z=X02AMF, the safe range parameter.
7:   H – REAL (KIND=nag_wp)Input
On entry: the barrier price.
Constraint: H≥z ​ and ​H≤1/z, where z=X02AMF, the safe range parameter.
8:   K – REAL (KIND=nag_wp)Input
On entry: the value of a possible cash rebate to be paid if the option has not been knocked in (or out) before expiration.
Constraint: K≥0.0.
9:   T N – REAL (KIND=nag_wp) arrayInput
On entry: T i must contain Ti, the ith time, in years, to expiry, for i=1,2,…,N.
Constraint: T i≥z, where z = X02AMF , the safe range parameter, for i=1,2,…,N.
10:   SIGMA – REAL (KIND=nag_wp)Input
On entry: σ, the volatility of the underlying asset. Note that a rate of 15% should be entered as 0.15.
Constraint: SIGMA>0.0.
11:   R – REAL (KIND=nag_wp)Input
On entry: r, the annual risk-free interest rate, continuously compounded. Note that a rate of 5% should be entered as 0.05.
Constraint: R≥0.0.
12:   Q – REAL (KIND=nag_wp)Input
On entry: q, the annual continuous yield rate. Note that a rate of 8% should be entered as 0.08.
Constraint: Q≥0.0.
13:   P LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: P ij contains P ij, the option price evaluated for the strike price Xi at expiry Tj for i=1,2,…,M and j=1,2,…,N.
14:   LDP – INTEGERInput
On entry: the first dimension of the array P as declared in the (sub)program from which S30FAF is called.
Constraint: LDP≥M.
15:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, CALPUT=value was an illegal value.
IFAIL=2
On entry, TYPE=value was an illegal value.
IFAIL=3
On entry, M=value.
Constraint: M≥1.
IFAIL=4
On entry, N=value.
Constraint: N≥1.
IFAIL=5
On entry, X value=value.
Constraint: X i≥value and X i≤value.
IFAIL=6
On entry, S=value.
Constraint: S≥value and S≤value.
IFAIL=7
On entry, H=value.
Constraint: H≥value and H≤value.
IFAIL=8
On entry, K=value.
Constraint: K≥0.0.
IFAIL=9
On entry, T value=value.
Constraint: T i≥value.
IFAIL=10
On entry, SIGMA=value.
Constraint: SIGMA>0.0.
IFAIL=11
On entry, R=value.
Constraint: R≥0.0.
IFAIL=12
On entry, Q=value.
Constraint: Q≥0.0.
IFAIL=14
On entry, LDP=value and M=value.
Constraint: LDP≥M.
IFAIL=15
On entry, S and H are inconsistent with TYPE: S=value and H=value.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The accuracy of the output is dependent on the accuracy of the cumulative Normal distribution function, Φ. This is evaluated using a rational Chebyshev expansion, chosen so that the maximum relative error in the expansion is of the order of the machine precision (see S15ABF and S15ADF). An accuracy close to machine precision can generally be expected.

8 Parallelism and Performance

S30FAF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

None.

10 Example

This example computes the price of a Down-and-In put with a time to expiry of 6 months, a stock price of 100 and a strike price of 100. The barrier value is 95 and there is a cash rebate of 3, payable on expiry if the option has not been knocked in. The risk-free interest rate is 8% per year, there is an annual dividend return of 4% and the volatility is 30% per year.

10.1 Program Text

Program Text (s30fafe.f90)

10.2 Program Data

Program Data (s30fafe.d)

10.3 Program Results

Program Results (s30fafe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S30JAF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S30JAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S30JAF computes the European option price using the Merton jump-diffusion model.

2 Specification

SUBROUTINE S30JAF ( CALPUT, M, N, X, S, T, SIGMA, R, LAMBDA, JVOL, P, LDP, IFAIL)
INTEGER | M, N, LDP, IFAIL
REAL (KIND=nag_wp) | X(M), S, T(N), SIGMA, R, LAMBDA, JVOL, P(LDP,N)
CHARACTER(1) | CALPUT

3 Description

S30JAF uses Merton's jump-diffusion model (Merton (1976)) to compute the price of a European option. This assumes that the asset price is described by a Brownian motion with drift, as in the Black–Scholes–Merton case, together with a compound Poisson process to model the jumps. The corresponding stochastic differential equation is,
dS S = α-λk dt + σ^ dW t + dq t .
Here α is the instantaneous expected return on the asset price, S; σ^2 is the instantaneous variance of the return when the Poisson event does not occur; dW t is a standard Brownian motion; qt is the independent Poisson process and k=E Y-1 where Y-1 is the random variable change in the stock price if the Poisson event occurs and E is the expectation operator over the random variable Y.
This leads to the following price for a European option (see Haug (2007))
Pcall = ∑ j=0 ∞ e-λT λT j j! Cj S, X, T, r, σj′ ,
where T is the time to expiry; X is the strike price; r is the annual risk-free interest rate; Cj S,X,T,r,σj′ is the Black–Scholes–Merton option pricing formula for a European call (see S30AAF).
σj′ = z 2 + δ 2 j T , z 2 = σ 2 - λ δ 2 , δ 2 = γ σ 2 λ ,
where σ is the total volatility including jumps; λ is the expected number of jumps given as an average per year; γ is the proportion of the total volatility due to jumps.
The value of a put is obtained by substituting the Black–Scholes–Merton put price for Cj S, X, T, r, σj′ .
The option price P ij=P X=Xi,T=Tj is computed for each strike price in a set Xi, i=1,2,…,m, and for each expiry time in a set Tj, j=1,2,…,n.

4 References

Haug E G (2007) The Complete Guide to Option Pricing Formulas (2nd Edition) McGraw-Hill
Merton R C (1976) Option pricing when underlying stock returns are discontinuous Journal of Financial Economics 3 125–144

5 Arguments

1:   CALPUT – CHARACTER(1)Input
On entry: determines whether the option is a call or a put.
CALPUT='C'
A call; the holder has a right to buy.
CALPUT='P'
A put; the holder has a right to sell.
Constraint: CALPUT='C' or 'P'.
2:   M – INTEGERInput
On entry: the number of strike prices to be used.
Constraint: M≥1.
3:   N – INTEGERInput
On entry: the number of times to expiry to be used.
Constraint: N≥1.
4:   X M – REAL (KIND=nag_wp) arrayInput
On entry: X i must contain Xi, the ith strike price, for i=1,2,…,M.
Constraint: X i≥z ​ and ​ X i ≤ 1 / z , where z = X02AMF , the safe range parameter, for i=1,2,…,M.
5:   S – REAL (KIND=nag_wp)Input
On entry: S, the price of the underlying asset.
Constraint: S≥z ​ and ​S≤1.0/z, where z=X02AMF, the safe range parameter.
6:   T N – REAL (KIND=nag_wp) arrayInput
On entry: T i must contain Ti, the ith time, in years, to expiry, for i=1,2,…,N.
Constraint: T i≥z, where z = X02AMF , the safe range parameter, for i=1,2,…,N.
7:   SIGMA – REAL (KIND=nag_wp)Input
On entry: σ, the annual total volatility, including jumps.
Constraint: SIGMA>0.0.
8:   R – REAL (KIND=nag_wp)Input
On entry: r, the annual risk-free interest rate, continuously compounded. Note that a rate of 5% should be entered as 0.05.
Constraint: R≥0.0.
9:   LAMBDA – REAL (KIND=nag_wp)Input
On entry: λ, the number of expected jumps per year.
Constraint: LAMBDA>0.0.
10:   JVOL – REAL (KIND=nag_wp)Input
On entry: the proportion of the total volatility associated with jumps.
Constraint: 0.0≤JVOL<1.0.
11:   P LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: P ij contains P ij, the option price evaluated for the strike price Xi at expiry Tj for i=1,2,…,M and j=1,2,…,N.
12:   LDP – INTEGERInput
On entry: the first dimension of the array P as declared in the (sub)program from which S30JAF is called.
Constraint: LDP≥M.
13:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, CALPUT=value was an illegal value.
IFAIL=2
On entry, M=value.
Constraint: M≥1.
IFAIL=3
On entry, N=value.
Constraint: N≥1.
IFAIL=4
On entry, X value=value.
Constraint: X i≥value and X i≤value.
IFAIL=5
On entry, S=value.
Constraint: S≥value and S≤value.
IFAIL=6
On entry, T value=value.
Constraint: T i≥value.
IFAIL=7
On entry, SIGMA=value.
Constraint: SIGMA>0.0.
IFAIL=8
On entry, R=value.
Constraint: R≥0.0.
IFAIL=9
On entry, LAMBDA=value.
Constraint: LAMBDA>0.0.
IFAIL=10
On entry, JVOL=value.
Constraint: JVOL≥0.0 and JVOL < 1.0.
IFAIL=12
On entry, LDP=value and M=value.
Constraint: LDP≥M.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The accuracy of the output is dependent on the accuracy of the cumulative Normal distribution function, Φ, occurring in Cj. This is evaluated using a rational Chebyshev expansion, chosen so that the maximum relative error in the expansion is of the order of the machine precision (see S15ABF and S15ADF). An accuracy close to machine precision can generally be expected.

8 Parallelism and Performance

S30JAF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
S30JAF makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

None.

10 Example

This example computes the price of a European call with jumps. The time to expiry is 3 months, the stock price is 45 and the strike price is 55. The number of jumps per year is 3 and the percentage of the total volatility due to jumps is 40%. The risk-free interest rate is 10% per year and the total volatility is 25% per year.

10.1 Program Text

Program Text (s30jafe.f90)

10.2 Program Data

Program Data (s30jafe.d)

10.3 Program Results

Program Results (s30jafe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S30JBF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S30JBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S30JBF computes the European option price together with its sensitivities (Greeks) using the Merton jump-diffusion model.

2 Specification

SUBROUTINE S30JBF ( CALPUT, M, N, X, S, T, SIGMA, R, LAMBDA, JVOL, P, LDP, DELTA, GAMMA, VEGA, THETA, RHO, VANNA, CHARM, SPEED, COLOUR, ZOMMA, VOMMA, IFAIL)
INTEGER | M, N, LDP, IFAIL
REAL (KIND=nag_wp) | X(M), S, T(N), SIGMA, R, LAMBDA, JVOL, P(LDP,N), DELTA(LDP,N), GAMMA(LDP,N), VEGA(LDP,N), THETA(LDP,N), RHO(LDP,N), VANNA(LDP,N), CHARM(LDP,N), SPEED(LDP,N), COLOUR(LDP,N), ZOMMA(LDP,N), VOMMA(LDP,N)
CHARACTER(1) | CALPUT

3 Description

S30JBF uses Merton's jump-diffusion model (Merton (1976)) to compute the price of a European option, together with the Greeks or sensitivities, which are the partial derivatives of the option price with respect to certain of the other input parameters. Merton's model assumes that the asset price is described by a Brownian motion with drift, as in the Black–Scholes–Merton case, together with a compound Poisson process to model the jumps. The corresponding stochastic differential equation is,
dS S = α-λk dt + σ^ dW t + dq t .
Here α is the instantaneous expected return on the asset price, S; σ^2 is the instantaneous variance of the return when the Poisson event does not occur; dW t is a standard Brownian motion; qt is the independent Poisson process and k=E Y-1 where Y-1 is the random variable change in the stock price if the Poisson event occurs and E is the expectation operator over the random variable Y.
This leads to the following price for a European option (see Haug (2007))
Pcall = ∑ j=0 ∞ e-λT λT j j! Cj S, X, T, r, σj′ ,
where T is the time to expiry; X is the strike price; r is the annual risk-free interest rate; Cj S,X,T,r,σj′ is the Black–Scholes–Merton option pricing formula for a European call (see S30AAF).
σj′ = z 2 + δ 2 j T , z 2 = σ 2 - λ δ 2 , δ 2 = γ σ 2 λ ,
where σ is the total volatility including jumps; λ is the expected number of jumps given as an average per year; γ is the proportion of the total volatility due to jumps.
The value of a put is obtained by substituting the Black–Scholes–Merton put price for Cj S, X, T, r, σj′ .
The option price P ij=P X=Xi,T=Tj is computed for each strike price in a set Xi, i=1,2,…,m, and for each expiry time in a set Tj, j=1,2,…,n.

4 References

Haug E G (2007) The Complete Guide to Option Pricing Formulas (2nd Edition) McGraw-Hill
Merton R C (1976) Option pricing when underlying stock returns are discontinuous Journal of Financial Economics 3 125–144

5 Arguments

1:   CALPUT – CHARACTER(1)Input
On entry: determines whether the option is a call or a put.
CALPUT='C'
A call; the holder has a right to buy.
CALPUT='P'
A put; the holder has a right to sell.
Constraint: CALPUT='C' or 'P'.
2:   M – INTEGERInput
On entry: the number of strike prices to be used.
Constraint: M≥1.
3:   N – INTEGERInput
On entry: the number of times to expiry to be used.
Constraint: N≥1.
4:   X M – REAL (KIND=nag_wp) arrayInput
On entry: X i must contain Xi, the ith strike price, for i=1,2,…,M.
Constraint: X i≥z ​ and ​ X i ≤ 1 / z , where z = X02AMF , the safe range parameter, for i=1,2,…,M.
5:   S – REAL (KIND=nag_wp)Input
On entry: S, the price of the underlying asset.
Constraint: S≥z ​ and ​S≤1.0/z, where z=X02AMF, the safe range parameter.
6:   T N – REAL (KIND=nag_wp) arrayInput
On entry: T i must contain Ti, the ith time, in years, to expiry, for i=1,2,…,N.
Constraint: T i≥z, where z = X02AMF , the safe range parameter, for i=1,2,…,N.
7:   SIGMA – REAL (KIND=nag_wp)Input
On entry: σ, the annual total volatility, including jumps.
Constraint: SIGMA>0.0.
8:   R – REAL (KIND=nag_wp)Input
On entry: r, the annual risk-free interest rate, continuously compounded. Note that a rate of 5% should be entered as 0.05.
Constraint: R≥0.0.
9:   LAMBDA – REAL (KIND=nag_wp)Input
On entry: λ, the number of expected jumps per year.
Constraint: LAMBDA>0.0.
10:   JVOL – REAL (KIND=nag_wp)Input
On entry: the proportion of the total volatility associated with jumps.
Constraint: 0.0≤JVOL<1.0.
11:   P LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: P ij contains P ij, the option price evaluated for the strike price Xi at expiry Tj for i=1,2,…,M and j=1,2,…,N.
12:   LDP – INTEGERInput
On entry: the first dimension of the arrays P, DELTA, GAMMA, VEGA, THETA, RHO, VANNA, CHARM, SPEED, COLOUR, ZOMMA and VOMMA as declared in the (sub)program from which S30JBF is called.
Constraint: LDP≥M.
13:   DELTA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: the leading M×N part of the array DELTA contains the sensitivity, ∂P∂S, of the option price to change in the price of the underlying asset.
14:   GAMMA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: the leading M×N part of the array GAMMA contains the sensitivity, ∂2 P∂S 2, of DELTA to change in the price of the underlying asset.
15:   VEGA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: VEGA ij, contains the first-order Greek measuring the sensitivity of the option price P ij to change in the volatility of the underlying asset, i.e., ∂P ij ∂σ , for i=1,2,…,M and j=1,2,…,N.
16:   THETA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: THETA ij, contains the first-order Greek measuring the sensitivity of the option price P ij to change in time, i.e., - ∂P ij ∂T , for i=1,2,…,M and j=1,2,…,N, where b=r-q.
17:   RHO LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: RHO ij, contains the first-order Greek measuring the sensitivity of the option price P ij to change in the annual risk-free interest rate, i.e., - ∂P ij ∂r , for i=1,2,…,M and j=1,2,…,N.
18:   VANNA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: VANNA ij, contains the second-order Greek measuring the sensitivity of the first-order Greek Δ ij to change in the volatility of the asset price, i.e., - ∂Δ ij ∂T = - ∂2 P ij ∂S∂σ , for i=1,2,…,M and j=1,2,…,N.
19:   CHARM LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: CHARM ij, contains the second-order Greek measuring the sensitivity of the first-order Greek Δ ij to change in the time, i.e., - ∂Δ ij ∂T = - ∂2 P ij ∂S∂T , for i=1,2,…,M and j=1,2,…,N.
20:   SPEED LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: SPEED ij, contains the third-order Greek measuring the sensitivity of the second-order Greek Γ ij to change in the price of the underlying asset, i.e., - ∂Γ ij ∂S = - ∂3 P ij ∂S 3 , for i=1,2,…,M and j=1,2,…,N.
21:   COLOUR LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: COLOUR ij, contains the third-order Greek measuring the sensitivity of the second-order Greek Γ ij to change in the time, i.e., - ∂Γ ij ∂T = - ∂3 P ij ∂S∂T , for i=1,2,…,M and j=1,2,…,N.
22:   ZOMMA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: ZOMMA ij, contains the third-order Greek measuring the sensitivity of the second-order Greek Γ ij to change in the volatility of the underlying asset, i.e., - ∂Γ ij ∂σ = - ∂3 P ij ∂S 2∂σ , for i=1,2,…,M and j=1,2,…,N.
23:   VOMMA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: VOMMA ij, contains the second-order Greek measuring the sensitivity of the first-order Greek Δ ij to change in the volatility of the underlying asset, i.e., - ∂Δ ij ∂σ = - ∂2 P ij ∂σ 2 , for i=1,2,…,M and j=1,2,…,N.
24:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, CALPUT=value was an illegal value.
IFAIL=2
On entry, M=value.
Constraint: M≥1.
IFAIL=3
On entry, N=value.
Constraint: N≥1.
IFAIL=4
On entry, X value=value.
Constraint: X i≥value and X i≤value.
IFAIL=5
On entry, S=value.
Constraint: S≥value and S≤value.
IFAIL=6
On entry, T value=value.
Constraint: T i≥value.
IFAIL=7
On entry, SIGMA=value.
Constraint: SIGMA>0.0.
IFAIL=8
On entry, R=value.
Constraint: R≥0.0.
IFAIL=9
On entry, LAMBDA=value.
Constraint: LAMBDA>0.0.
IFAIL=10
On entry, JVOL=value.
Constraint: JVOL≥0.0 and JVOL < 1.0.
IFAIL=12
On entry, LDP=value and M=value.
Constraint: LDP≥M.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The accuracy of the output is dependent on the accuracy of the cumulative Normal distribution function, Φ, occurring in Cj. This is evaluated using a rational Chebyshev expansion, chosen so that the maximum relative error in the expansion is of the order of the machine precision (see S15ABF and S15ADF). An accuracy close to machine precision can generally be expected.

8 Parallelism and Performance

S30JBF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

None.

10 Example

This example computes the price of two European calls with jumps. The time to expiry is 6 months, the stock price is 100 and strike prices are 80 and 90 respectively. The number of jumps per year is 5 and the percentage of the total volatility due to jumps is 25%. The risk-free interest rate is 8% per year while the total volatility is 25% per year.

10.1 Program Text

Program Text (s30jbfe.f90)

10.2 Program Data

Program Data (s30jbfe.d)

10.3 Program Results

Program Results (s30jbfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S30NAF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S30NAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S30NAF computes the European option price given by Heston's stochastic volatility model.

2 Specification

SUBROUTINE S30NAF ( CALPUT, M, N, X, S, T, SIGMAV, KAPPA, CORR, VAR0, ETA, GRISK, R, Q, P, LDP, IFAIL)
INTEGER | M, N, LDP, IFAIL
REAL (KIND=nag_wp) | X(M), S, T(N), SIGMAV, KAPPA, CORR, VAR0, ETA, GRISK, R, Q, P(LDP,N)
CHARACTER(1) | CALPUT

3 Description

S30NAF computes the price of a European option using Heston's stochastic volatility model. The return on the asset price, S, is
dS S = r-q dt + vt d W t 1
and the instantaneous variance, vt, is defined by a mean-reverting square root stochastic process,
d vt = κ η-vt dt + σv vt d W t 2 ,
where r is the risk free annual interest rate; q is the annual dividend rate; vt is the variance of the asset price; σv is the volatility of the volatility, vt; κ is the mean reversion rate; η is the long term variance. d Wt i, for i=1,2, denotes two correlated standard Brownian motions with
ℂov d W t 1 , d W t 2 = ρ d t .
The option price is computed by evaluating the integral transform given by Lewis (2000) using the form of the characteristic function discussed by Albrecher et al. (2007), see also Kilin (2006).
Pcall = S e-qT - X e-rT 1 π Re ∫ 0+i/2 ∞+i/2 e-ik X- H^ k,v,T k 2 - ik d k , (1)
where X- = ln S/X + r-q T and
H^ k,v,T = exp 2 κη σv 2 tg - ln 1-h e-ξt 1-h + vt g 1-e-ξt 1-h e-ξt ,
g = 12 b-ξ ,   h = b-ξ b+ξ ,   t = σv 2 T/2 ,
ξ = b 2 + 4 k 2-ik σv 2 12 ,
b = 2 σv 2 1-γ+ik ρ σv + κ 2 - γ 1-γ σv 2
with t = σv 2 T/2 . Here γ is the risk aversion parameter of the representative agent with 0≤γ≤1 and γ 1-γ σv 2 ≤ κ 2 . The value γ=1 corresponds to λ=0, where λ is the market price of risk in Heston (1993) (see Lewis (2000) and Rouah and Vainberg (2007)).
The price of a put option is obtained by put-call parity.
The option price P ij=P X=Xi,T=Tj is computed for each strike price in a set Xi, i=1,2,…,m, and for each expiry time in a set Tj, j=1,2,…,n.

4 References

Albrecher H, Mayer P, Schoutens W and Tistaert J (2007) The little Heston trap Wilmott Magazine January 2007 83–92
Heston S (1993) A closed-form solution for options with stochastic volatility with applications to bond and currency options Review of Financial Studies 6 327–343
Kilin F (2006) Accelerating the calibration of stochastic volatility models MPRA Paper No. 2975 http://mpra.ub.uni-muenchen.de/2975/
Lewis A L (2000) Option valuation under stochastic volatility Finance Press, USA
Rouah F D and Vainberg G (2007) Option Pricing Models and Volatility using Excel-VBA John Wiley and Sons, Inc

5 Arguments

1:   CALPUT – CHARACTER(1)Input
On entry: determines whether the option is a call or a put.
CALPUT='C'
A call; the holder has a right to buy.
CALPUT='P'
A put; the holder has a right to sell.
Constraint: CALPUT='C' or 'P'.
2:   M – INTEGERInput
On entry: the number of strike prices to be used.
Constraint: M≥1.
3:   N – INTEGERInput
On entry: the number of times to expiry to be used.
Constraint: N≥1.
4:   X M – REAL (KIND=nag_wp) arrayInput
On entry: X i must contain Xi, the ith strike price, for i=1,2,…,M.
Constraint: X i≥z ​ and ​ X i ≤ 1 / z , where z = X02AMF , the safe range parameter, for i=1,2,…,M.
5:   S – REAL (KIND=nag_wp)Input
On entry: S, the price of the underlying asset.
Constraint: S≥z ​ and ​S≤1.0/z, where z=X02AMF, the safe range parameter.
6:   T N – REAL (KIND=nag_wp) arrayInput
On entry: T i must contain Ti, the ith time, in years, to expiry, for i=1,2,…,N.
Constraint: T i≥z, where z = X02AMF , the safe range parameter, for i=1,2,…,N.
7:   SIGMAV – REAL (KIND=nag_wp)Input
On entry: the volatility, σv, of the volatility process, vt. Note that a rate of 20% should be entered as 0.2.
Constraint: SIGMAV>0.0.
8:   KAPPA – REAL (KIND=nag_wp)Input
On entry: κ, the long term mean reversion rate of the volatility.
Constraint: KAPPA>0.0.
9:   CORR – REAL (KIND=nag_wp)Input
On entry: the correlation between the two standard Brownian motions for the asset price and the volatility.
Constraint: -1.0≤CORR≤1.0.
10:   VAR0 – REAL (KIND=nag_wp)Input
On entry: the initial value of the variance, vt, of the asset price.
Constraint: VAR0≥0.0.
11:   ETA – REAL (KIND=nag_wp)Input
On entry: η, the long term mean of the variance of the asset price.
Constraint: ETA>0.0.
12:   GRISK – REAL (KIND=nag_wp)Input
On entry: the risk aversion parameter, γ, of the representative agent.
Constraint: 0.0≤GRISK≤1.0 and GRISK×1.0-GRISK×SIGMAV×SIGMAV≤KAPPA×KAPPA.
13:   R – REAL (KIND=nag_wp)Input
On entry: r, the annual risk-free interest rate, continuously compounded. Note that a rate of 5% should be entered as 0.05.
Constraint: R≥0.0.
14:   Q – REAL (KIND=nag_wp)Input
On entry: q, the annual continuous yield rate. Note that a rate of 8% should be entered as 0.08.
Constraint: Q≥0.0.
15:   P LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: P ij contains P ij, the option price evaluated for the strike price Xi at expiry Tj for i=1,2,…,M and j=1,2,…,N.
16:   LDP – INTEGERInput
On entry: the first dimension of the array P as declared in the (sub)program from which S30NAF is called.
Constraint: LDP≥M.
17:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, CALPUT=value was an illegal value.
IFAIL=2
On entry, M=value.
Constraint: M≥1.
IFAIL=3
On entry, N=value.
Constraint: N≥1.
IFAIL=4
On entry, X value=value.
Constraint: X i≥value and X i≤value.
IFAIL=5
On entry, S=value.
Constraint: S≥value and S≤value.
IFAIL=6
On entry, T value=value.
Constraint: T i≥value.
IFAIL=7
On entry, SIGMAV=value.
Constraint: SIGMAV>0.0.
IFAIL=8
On entry, KAPPA=value.
Constraint: KAPPA>0.0.
IFAIL=9
On entry, CORR=value.
Constraint: CORR≤1.0.
IFAIL=10
On entry, VAR0=value.
Constraint: VAR0≥0.0.
IFAIL=11
On entry, ETA=value.
Constraint: ETA>0.0.
IFAIL=12
On entry, GRISK=value, SIGMAV=value and KAPPA=value.
Constraint: 0.0≤GRISK≤1.0 and GRISK×1.0-GRISK×SIGMAV 2≤KAPPA 2.
IFAIL=13
On entry, R=value.
Constraint: R≥0.0.
IFAIL=14
On entry, Q=value.
Constraint: Q≥0.0.
IFAIL=16
On entry, LDP=value and M=value.
Constraint: LDP≥M.
IFAIL=17
Quadrature has not converged to the specified accuracy. However, the result should be a reasonable approximation.
IFAIL=18
Solution cannot be computed accurately. Check values of input arguments.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The accuracy of the output is determined by the accuracy of the numerical quadrature used to evaluate the integral in (1). An adaptive method is used which evaluates the integral to within a tolerance of max 10 -8 , 10 -10 × I , where I is the absolute value of the integral.

8 Parallelism and Performance

S30NAF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

None.

10 Example

This example computes the price of a European call using Heston's stochastic volatility model. The time to expiry is 6 months, the stock price is 100 and the strike price is 100. The risk-free interest rate is 5% per year, the volatility of the variance, σv, is 22.5% per year, the mean reversion parameter, κ, is 2.0, the long term mean of the variance, η, is 0.01 and the correlation between the volatility process and the stock price process, ρ, is 0.0. The risk aversion parameter, γ, is 1.0 and the initial value of the variance, VAR0, is 0.01.

10.1 Program Text

Program Text (s30nafe.f90)

10.2 Program Data

Program Data (s30nafe.d)

10.3 Program Results

Program Results (s30nafe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S30NBF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S30NBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S30NBF computes the European option price given by Heston's stochastic volatility model together with its sensitivities (Greeks).

2 Specification

SUBROUTINE S30NBF ( CALPUT, M, N, X, S, T, SIGMAV, KAPPA, CORR, VAR0, ETA, GRISK, R, Q, P, LDP, DELTA, GAMMA, VEGA, THETA, RHO, VANNA, CHARM, SPEED, ZOMMA, VOMMA, IFAIL)
INTEGER | M, N, LDP, IFAIL
REAL (KIND=nag_wp) | X(M), S, T(N), SIGMAV, KAPPA, CORR, VAR0, ETA, GRISK, R, Q, P(LDP,N), DELTA(LDP,N), GAMMA(LDP,N), VEGA(LDP,N), THETA(LDP,N), RHO(LDP,N), VANNA(LDP,N), CHARM(LDP,N), SPEED(LDP,N), ZOMMA(LDP,N), VOMMA(LDP,N)
CHARACTER(1) | CALPUT

3 Description

S30NBF computes the price and sensitivities of a European option using Heston's stochastic volatility model. The return on the asset price, S, is
dS S = r-q dt + vt d W t 1
and the instantaneous variance, vt, is defined by a mean-reverting square root stochastic process,
d vt = κ η-vt dt + σv vt d W t 2 ,
where r is the risk free annual interest rate; q is the annual dividend rate; vt is the variance of the asset price; σv is the volatility of the volatility, vt; κ is the mean reversion rate; η is the long term variance. d Wt i, for i=1,2, denotes two correlated standard Brownian motions with
ℂov d W t 1 , d W t 2 = ρ d t .
The option price is computed by evaluating the integral transform given by Lewis (2000) using the form of the characteristic function discussed by Albrecher et al. (2007), see also Kilin (2006).
Pcall = S e-qT - X e-rT 1 π Re ∫ 0+i/2 ∞+i/2 e-ik X- H^ k,v,T k 2 - ik d k , (1)
where X- = ln S/X + r-q T and
H^ k,v,T = exp 2 κη σv 2 tg - ln 1-h e-ξt 1-h + vt g 1-e-ξt 1-h e-ξt ,
g = 12 b-ξ ,   h = b-ξ b+ξ ,   t = σv 2 T/2 ,
ξ = b 2 + 4 k 2-ik σv 2 12 ,
b = 2 σv 2 1-γ+ik ρ σv + κ 2 - γ 1-γ σv 2
with t = σv 2 T/2 . Here γ is the risk aversion parameter of the representative agent with 0≤γ≤1 and γ 1-γ σv 2 ≤ κ 2 . The value γ=1 corresponds to λ=0, where λ is the market price of risk in Heston (1993) (see Lewis (2000) and Rouah and Vainberg (2007)).
The price of a put option is obtained by put-call parity.
Pput = Pcall + X e-rT - S e-qT .
Writing the expression for the price of a call option as
Pcall = S e-qT - X e-rT 1 π Re ∫ 0+i/2 ∞+i/2 I k,r,S,T,v d k
then the sensitivities or Greeks can be obtained in the following manner,
Delta
∂ Pcall ∂S = e-qT + X e-rT S 1 π Re ∫ 0+i/2 ∞+i/2 ik I k,r,S,T,v dk ,
Vega
∂P ∂v = - X e-rT 1 π Re ∫ 0-i/2 0+i/2 f 2 I k,r,j,S,T,v dk ,  where ​ f 2 = g 1 - e-ξt 1 - h e-ξt ,
Rho
∂Pcall ∂r = T X e-rT 1 π Re ∫ 0+i/2 ∞+i/2 1+ik I k,r,S,T,v dk .
The option price P ij=P X=Xi,T=Tj is computed for each strike price in a set Xi, i=1,2,…,m, and for each expiry time in a set Tj, j=1,2,…,n.

4 References

Albrecher H, Mayer P, Schoutens W and Tistaert J (2007) The little Heston trap Wilmott Magazine January 2007 83–92
Heston S (1993) A closed-form solution for options with stochastic volatility with applications to bond and currency options Review of Financial Studies 6 327–343
Kilin F (2006) Accelerating the calibration of stochastic volatility models MPRA Paper No. 2975 http://mpra.ub.uni-muenchen.de/2975/
Lewis A L (2000) Option valuation under stochastic volatility Finance Press, USA
Rouah F D and Vainberg G (2007) Option Pricing Models and Volatility using Excel-VBA John Wiley and Sons, Inc

5 Arguments

1:   CALPUT – CHARACTER(1)Input
On entry: determines whether the option is a call or a put.
CALPUT='C'
A call; the holder has a right to buy.
CALPUT='P'
A put; the holder has a right to sell.
Constraint: CALPUT='C' or 'P'.
2:   M – INTEGERInput
On entry: the number of strike prices to be used.
Constraint: M≥1.
3:   N – INTEGERInput
On entry: the number of times to expiry to be used.
Constraint: N≥1.
4:   X M – REAL (KIND=nag_wp) arrayInput
On entry: X i must contain Xi, the ith strike price, for i=1,2,…,M.
Constraint: X i≥z ​ and ​ X i ≤ 1 / z , where z = X02AMF , the safe range parameter, for i=1,2,…,M.
5:   S – REAL (KIND=nag_wp)Input
On entry: S, the price of the underlying asset.
Constraint: S≥z ​ and ​S≤1.0/z, where z=X02AMF, the safe range parameter.
6:   T N – REAL (KIND=nag_wp) arrayInput
On entry: T i must contain Ti, the ith time, in years, to expiry, for i=1,2,…,N.
Constraint: T i≥z, where z = X02AMF , the safe range parameter, for i=1,2,…,N.
7:   SIGMAV – REAL (KIND=nag_wp)Input
On entry: the volatility, σv, of the volatility process, vt. Note that a rate of 20% should be entered as 0.2.
Constraint: SIGMAV>0.0.
8:   KAPPA – REAL (KIND=nag_wp)Input
On entry: κ, the long term mean reversion rate of the volatility.
Constraint: KAPPA>0.0.
9:   CORR – REAL (KIND=nag_wp)Input
On entry: the correlation between the two standard Brownian motions for the asset price and the volatility.
Constraint: -1.0≤CORR≤1.0.
10:   VAR0 – REAL (KIND=nag_wp)Input
On entry: the initial value of the variance, vt, of the asset price.
Constraint: VAR0≥0.0.
11:   ETA – REAL (KIND=nag_wp)Input
On entry: η, the long term mean of the variance of the asset price.
Constraint: ETA>0.0.
12:   GRISK – REAL (KIND=nag_wp)Input
On entry: the risk aversion parameter, γ, of the representative agent.
Constraint: 0.0≤GRISK≤1.0 and GRISK×1-GRISK×SIGMAV×SIGMAV≤KAPPA×KAPPA.
13:   R – REAL (KIND=nag_wp)Input
On entry: r, the annual risk-free interest rate, continuously compounded. Note that a rate of 5% should be entered as 0.05.
Constraint: R≥0.0.
14:   Q – REAL (KIND=nag_wp)Input
On entry: q, the annual continuous yield rate. Note that a rate of 8% should be entered as 0.08.
Constraint: Q≥0.0.
15:   P LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: P ij contains P ij, the option price evaluated for the strike price Xi at expiry Tj for i=1,2,…,M and j=1,2,…,N.
16:   LDP – INTEGERInput
On entry: the first dimension of the arrays P, DELTA, GAMMA, VEGA, THETA, RHO, VANNA, CHARM, SPEED, ZOMMA and VOMMA as declared in the (sub)program from which S30NBF is called.
Constraint: LDP≥M.
17:   DELTA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: the leading M×N part of the array DELTA contains the sensitivity, ∂P∂S, of the option price to change in the price of the underlying asset.
18:   GAMMA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: the leading M×N part of the array GAMMA contains the sensitivity, ∂2 P∂S 2, of DELTA to change in the price of the underlying asset.
19:   VEGA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: VEGA ij, contains the first-order Greek measuring the sensitivity of the option price P ij to change in the volatility of the underlying asset, i.e., ∂P ij ∂σ , for i=1,2,…,M and j=1,2,…,N.
20:   THETA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: THETA ij, contains the first-order Greek measuring the sensitivity of the option price P ij to change in time, i.e., - ∂P ij ∂T , for i=1,2,…,M and j=1,2,…,N, where b=r-q.
21:   RHO LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: RHO ij, contains the first-order Greek measuring the sensitivity of the option price P ij to change in the annual risk-free interest rate, i.e., - ∂P ij ∂r , for i=1,2,…,M and j=1,2,…,N.
22:   VANNA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: VANNA ij, contains the second-order Greek measuring the sensitivity of the first-order Greek Δ ij to change in the volatility of the asset price, i.e., - ∂Δ ij ∂T = - ∂2 P ij ∂S∂σ , for i=1,2,…,M and j=1,2,…,N.
23:   CHARM LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: CHARM ij, contains the second-order Greek measuring the sensitivity of the first-order Greek Δ ij to change in the time, i.e., - ∂Δ ij ∂T = - ∂2 P ij ∂S∂T , for i=1,2,…,M and j=1,2,…,N.
24:   SPEED LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: SPEED ij, contains the third-order Greek measuring the sensitivity of the second-order Greek Γ ij to change in the price of the underlying asset, i.e., - ∂Γ ij ∂S = - ∂3 P ij ∂S 3 , for i=1,2,…,M and j=1,2,…,N.
25:   ZOMMA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: ZOMMA ij, contains the third-order Greek measuring the sensitivity of the second-order Greek Γ ij to change in the volatility of the underlying asset, i.e., - ∂Γ ij ∂σ = - ∂3 P ij ∂S 2∂σ , for i=1,2,…,M and j=1,2,…,N.
26:   VOMMA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: VOMMA ij, contains the second-order Greek measuring the sensitivity of the first-order Greek Δ ij to change in the volatility of the underlying asset, i.e., - ∂Δ ij ∂σ = - ∂2 P ij ∂σ 2 , for i=1,2,…,M and j=1,2,…,N.
27:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, CALPUT=value was an illegal value.
IFAIL=2
On entry, M=value.
Constraint: M≥1.
IFAIL=3
On entry, N=value.
Constraint: N≥1.
IFAIL=4
On entry, X value=value.
Constraint: X i≥value and X i≤value.
IFAIL=5
On entry, S=value.
Constraint: S≥value and S≤value.
IFAIL=6
On entry, T value=value.
Constraint: T i≥value.
IFAIL=7
On entry, SIGMAV=value.
Constraint: SIGMAV>0.0.
IFAIL=8
On entry, KAPPA=value.
Constraint: KAPPA>0.0.
IFAIL=9
On entry, CORR=value.
Constraint: CORR≤1.0.
IFAIL=10
On entry, VAR0=value.
Constraint: VAR0≥0.0.
IFAIL=11
On entry, ETA=value.
Constraint: ETA>0.0.
IFAIL=12
On entry, GRISK=value, SIGMAV=value and KAPPA=value.
Constraint: 0.0≤GRISK≤1.0 and GRISK×1.0-GRISK×SIGMAV 2≤KAPPA 2.
IFAIL=13
On entry, R=value.
Constraint: R≥0.0.
IFAIL=14
On entry, Q=value.
Constraint: Q≥0.0.
IFAIL=16
On entry, LDP=value and M=value.
Constraint: LDP≥M.
IFAIL=17
Quadrature has not converged to the required accuracy. However, the result should be a reasonable approximation.
IFAIL=18
Solution cannot be computed accurately. Check values of input arguments.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The accuracy of the output is determined by the accuracy of the numerical quadrature used to evaluate the integral in (1). An adaptive method is used which evaluates the integral to within a tolerance of max 10 -8 , 10 -10 × I , where I is the absolute value of the integral.

8 Parallelism and Performance

S30NBF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

None.

10 Example

This example computes the price and sensitivities of a European call using Heston's stochastic volatility model. The time to expiry is 1 year, the stock price is 100 and the strike price is 100. The risk-free interest rate is 2.5% per year, the volatility of the variance, σv, is 57.51% per year, the mean reversion parameter, κ, is 1.5768, the long term mean of the variance, η, is 0.0398 and the correlation between the volatility process and the stock price process, ρ, is -0.5711. The risk aversion parameter, γ, is 1.0 and the initial value of the variance, VAR0, is 0.0175.

10.1 Program Text

Program Text (s30nbfe.f90)

10.2 Program Data

Program Data (s30nbfe.d)

10.3 Program Results

Program Results (s30nbfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S30NCF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S30NCF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S30NCF computes the European option price given by Heston's stochastic volatility model with term structure.

2 Specification

SUBROUTINE S30NCF ( CALPUT, M, NUMTS, X, FWD, DISC, TS, T, ALPHA, LAMBDA, CORR, SIGMAT, VAR0, P, IFAIL)
INTEGER | M, NUMTS, IFAIL
REAL (KIND=nag_wp) | X(M), FWD, DISC, TS(NUMTS), T, ALPHA(NUMTS), LAMBDA(NUMTS), CORR(NUMTS), SIGMAT(NUMTS), VAR0, P(M)
CHARACTER(1) | CALPUT

3 Description

S30NCF computes the price of a European option for Heston's stochastic volatility model with time-dependent parameters which are piecewise constant. Starting from the stochastic volatility model given by the Stochastic Differential Equation (SDE) system defined by Heston (1993), a scaling of the variance process is introduced, together with a normalization, setting the long run variance, η, equal to 1. This leads to
d St St = μt d t+σt νt d Wt 1 , (1)
d νt = λt 1-νt d t+ αt νt d Wt 2 , (2)
Cov d W t 1 , d W t 2 = ρt d t , (3)
where μt=rt-qt is the drift term representing the contribution of interest rates, rt, and dividends, qt, while σt is the scaling parameter, νt is the scaled variance, λt is the mean reversion rate and αt is the volatility of the scaled volatility, νt. Then, Wt i, for i=1,2, are two standard Brownian motions with correlation parameter ρt. Without loss of generality, the drift term, μt, is eliminated by modelling the forward price, Ft, directly, instead of the spot price, St, with
Ft = S 0 exp ∫ 0 t μs d s . (4)
If required, the spot can be expressed as, S 0 = D Ft , where D is the discount factor.
The option price is computed by dividing the time to expiry, T, into ns subintervals t 0,t 1 , … , t i-1,ti , … , t ns-1,T and applying the method of characteristic functions to each subinterval, with appropriate initial conditions. Thus, a pair of ordinary differential equations (one of which is a Riccati equation) is solved on each subinterval as outlined in Elices (2008) and Mikhailov and Nögel (2003). Reversing time by taking τ=T-t, the characteristic function solution for the first time subinterval, starting at τ=0, is given by Heston (1993), while the solution on each following subinterval uses the solution of the preceding subinterval as initial condition to compute the value of the characteristic function.
In the case of a ‘flat’ term structure, i.e., the parameters are constant over the time of the option, T, the form of the SDE system given by Heston (1993) can be recovered by setting κ=λt, η=σt 2, σv=σtαt and V 0=σt 2 V 0.
Conversely, given the Heston form of the SDE pair, to get the term structure form set λt=κ, σt=η, αt=σv η and V 0=V 0 η.

4 References

Bain A (2011) Private communication
Elices A (2008) Models with time-dependent parameters using transform methods: application to Heston’s model arXiv:0708.2020v2
Heston S (1993) A closed-form solution for options with stochastic volatility with applications to bond and currency options Review of Financial Studies 6 327–343
Mikhailov S and Nögel U (2003) Heston’s Stochastic Volatility Model Implementation, Calibration and Some Extensions Wilmott Magazine July/August 74–79

5 Arguments

1:   CALPUT – CHARACTER(1)Input
On entry: determines whether the option is a call or a put.
CALPUT='C'
A call; the holder has a right to buy.
CALPUT='P'
A put; the holder has a right to sell.
Constraint: CALPUT='C' or 'P'.
2:   M – INTEGERInput
On entry: m, the number of strike prices to be used.
Constraint: M≥1.
3:   NUMTS – INTEGERInput
On entry: ns, the number of subintervals into which the time to expiry, T, is divided.
Constraint: NUMTS≥1.
4:   X M – REAL (KIND=nag_wp) arrayInput
On entry: X i contains the ith strike price, for i=1,2,…,m.
Constraint: X i≥z ​ and ​ X i ≤ 1 / z , where z = X02AMF , the safe range parameter, for i=1,2,…,M.
5:   FWD – REAL (KIND=nag_wp)Input
On entry: the forward price of the asset.
Constraint: FWD≥z and FWD≤1/z, where z=X02AMF, the safe range parameter.
6:   DISC – REAL (KIND=nag_wp)Input
On entry: the discount factor, where the current price of the underlying asset, S 0, is given as S 0=DISC×FWD.
Constraint: DISC≥z and DISC≤1/z, where z=X02AMF, the safe range parameter.
7:   TS NUMTS – REAL (KIND=nag_wp) arrayInput
On entry: TS i must contain the length of the time intervals for which the corresponding element of ALPHA, LAMBDA, CORR and SIGMAT apply. These should be ordered as they occur in time i.e., Δ ti = ti - t i-1.
Constraint: TS i≥z ​ and ​ TS i ≤ 1 / z , where z = X02AMF , the safe range parameter, for i=1,2,…,NUMTS.
8:   T – REAL (KIND=nag_wp)Input
On entry: T contains the time to expiry. If T > ∑ Δ ti then the parameters associated with the last time interval are extended to the expiry time. If T < ∑ Δ ti then the parameters specified are used up until the expiry time. The rest are ignored.
Constraint: T≥z, where z = X02AMF , the safe range parameter.
9:   ALPHA NUMTS – REAL (KIND=nag_wp) arrayInput
On entry: ALPHA i must contain the value of αt, the value of the volatility of the scaled volatility, ν, over time subinterval Δ ti.
Constraint: ALPHA i≥z ​ and ​ ALPHA i ≤ 1 / z , where z = X02AMF , the safe range parameter, for i=1,2,…,NUMTS.
10:   LAMBDA NUMTS – REAL (KIND=nag_wp) arrayInput
On entry: LAMBDA i must contain the value, λt, of the mean reversion parameter over the time subinterval Δ ti.
Constraint: LAMBDA i≥z ​ and ​ LAMBDA i ≤ 1 / z , where z = X02AMF , the safe range parameter, for i=1,2,…,NUMTS.
11:   CORR NUMTS – REAL (KIND=nag_wp) arrayInput
On entry: CORR i must contain the value, ρt, of the correlation parameter over the time subinterval Δ ti.
Constraint: -1.0≤CORR i≤1.0, for i=1,2,…,NUMTS.
12:   SIGMAT NUMTS – REAL (KIND=nag_wp) arrayInput
On entry: SIGMAT i must contain the value, σ t, of the variance scale factor over the time subinterval Δ ti.
Constraint: SIGMAT i≥z ​ and ​ SIGMAT i ≤ 1 / z , where z = X02AMF , the safe range parameter, for i=1,2,…,NUMTS.
13:   VAR0 – REAL (KIND=nag_wp)Input
On entry: ν 0, the initial scaled variance.
Constraint: VAR0≥0.0.
14:   P M – REAL (KIND=nag_wp) arrayOutput
On exit: P i contains the computed option price at the expiry time, T, corresponding to strike X i for the specified term structure, for i=1,2,…,M.
15:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, CALPUT=value was an illegal value.
IFAIL=2
On entry, M=value.
Constraint: M≥1.
IFAIL=3
On entry, NUMTS=value.
Constraint: NUMTS≥1.
IFAIL=4
On entry, X value=value.
Constraint: value≤X i≤value.
IFAIL=5
On entry, FWD=value.
Constraint: value≤FWD≤value.
IFAIL=6
On entry, DISC=value.
Constraint: value≤DISC≤value.
IFAIL=7
On entry, TS value=value.
Constraint: value≤TS i≤value.
IFAIL=8
On entry, T=value.
Constraint: T≥value.
IFAIL=9
On entry, ALPHA value=value.
Constraint: value≤ALPHA i≤value.
IFAIL=10
On entry, LAMBDA value=value.
Constraint: value≤LAMBDA i≤value.
IFAIL=11
On entry, CORR value=value.
Constraint: CORR i≤1.0.
IFAIL=12
On entry, SIGMAT value=value.
Constraint: value≤SIGMAT i≤value.
IFAIL=13
On entry, VAR0=value.
Constraint: VAR0>0.0.
IFAIL=14
Quadrature has not converged to the specified accuracy. However, the result should be a reasonable approximation.
IFAIL=15
Solution cannot be computed accurately. Check values of input arguments.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The solution is obtained by integrating the pair of ordinary differential equations over each subinterval in time. The accuracy is controlled by a relative tolerance over each time subinterval, which is set to 10 -8 . Over a number of subintervals in time the error may accumulate and so the overall error in the computation may be greater than this. A threshold of 10 -10 is used and solutions smaller than this are not accurately evaluated.

8 Parallelism and Performance

S30NCF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

None.

10 Example

This example computes the price of a European call using Heston's stochastic volatility model with a term structure of interest rates.

10.1 Program Text

Program Text (s30ncfe.f90)

10.2 Program Data

Program Data (s30ncfe.d)

10.3 Program Results

Program Results (s30ncfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S30QCF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S30QCF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S30QCF computes the Bjerksund and Stensland (2002) approximation to the price of an American option.

2 Specification

SUBROUTINE S30QCF ( CALPUT, M, N, X, S, T, SIGMA, R, Q, P, LDP, IFAIL)
INTEGER | M, N, LDP, IFAIL
REAL (KIND=nag_wp) | X(M), S, T(N), SIGMA, R, Q, P(LDP,N)
CHARACTER(1) | CALPUT

3 Description

S30QCF computes the price of an American option using the closed form approximation of Bjerksund and Stensland (2002). The time to maturity, T, is divided into two periods, each with a flat early exercise boundary, by choosing a time t ∈ 0,T , such that t = 12 5-1 T . The two boundary values are defined as x~=X~t, X~=X~T with
X~τ = B 0 + B∞ - B 0 1 - exp h τ ,
where
h τ = - bτ+2 σ⁢τ X 2 B∞ - B 0 B 0 ,
B∞ ≡ β β-1 X ,  B 0 ≡ max X, r r-b X ,
β = 12 - b σ 2 + b σ 2 - 12 2 + 2 r σ 2 .
with b=r-q, the cost of carry, where r is the risk-free interest rate and q is the annual dividend rate. Here X is the strike price and σ is the annual volatility.
The price of an American call option is approximated as
Pcall = α X~ Sβ - α X~ ϕ S,t|β,X~,X~+ ϕ S,t|1,X~,X~ - ϕ S,t|1,x~,X~ - X ϕ S,t|0,X~,X~ + X ϕ S,t|0,x~,X~ + α x~ ϕ S,t|β,x~,X~ - α x~ Ψ S,T|β,x~,X~,x~,t + Ψ S,T|1,x~,X~,x~,t - Ψ S,T|1,X,X~,x~,t - X Ψ S,T|0,x~,X~,x~,t + X Ψ S,T|0,X,X~,x~,t ,
where α, ϕ and Ψ are as defined in Bjerksund and Stensland (2002).
The price of a put option is obtained by the put-call transformation,
Pput X,S,T,σ,r,q = Pcall S,X,T,σ,q,r .
The option price P ij=P X=Xi,T=Tj is computed for each strike price in a set Xi, i=1,2,…,m, and for each expiry time in a set Tj, j=1,2,…,n.

4 References

Bjerksund P and Stensland G (2002) Closed form valuation of American options Discussion Paper 2002/09 NHH Bergen Norway http://www.nhh.no/
Genz A (2004) Numerical computation of rectangular bivariate and trivariate Normal and t probabilities Statistics and Computing 14 151–160

5 Arguments

1:   CALPUT – CHARACTER(1)Input
On entry: determines whether the option is a call or a put.
CALPUT='C'
A call; the holder has a right to buy.
CALPUT='P'
A put; the holder has a right to sell.
Constraint: CALPUT='C' or 'P'.
2:   M – INTEGERInput
On entry: the number of strike prices to be used.
Constraint: M≥1.
3:   N – INTEGERInput
On entry: the number of times to expiry to be used.
Constraint: N≥1.
4:   X M – REAL (KIND=nag_wp) arrayInput
On entry: X i must contain Xi, the ith strike price, for i=1,2,…,M.
Constraint: X i≥z ​ and ​ X i ≤ 1 / z , where z = X02AMF , the safe range parameter, for i=1,2,…,M.
5:   S – REAL (KIND=nag_wp)Input
On entry: S, the price of the underlying asset.
Constraint: S≥z ​ and ​S≤1 z, where z=X02AMF, the safe range parameter and Sβ<1 z where β is as defined in Section 3.
6:   T N – REAL (KIND=nag_wp) arrayInput
On entry: T i must contain Ti, the ith time, in years, to expiry, for i=1,2,…,N.
Constraint: T i≥z, where z = X02AMF , the safe range parameter, for i=1,2,…,N.
7:   SIGMA – REAL (KIND=nag_wp)Input
On entry: σ, the volatility of the underlying asset. Note that a rate of 15% should be entered as 0.15.
Constraint: SIGMA>0.0.
8:   R – REAL (KIND=nag_wp)Input
On entry: r, the annual risk-free interest rate, continuously compounded. Note that a rate of 5% should be entered as 0.05.
Constraint: R≥0.0.
9:   Q – REAL (KIND=nag_wp)Input
On entry: q, the annual continuous yield rate. Note that a rate of 8% should be entered as 0.08.
Constraint: Q≥0.0.
10:   P LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: P ij contains P ij, the option price evaluated for the strike price Xi at expiry Tj for i=1,2,…,M and j=1,2,…,N.
11:   LDP – INTEGERInput
On entry: the first dimension of the array P as declared in the (sub)program from which S30QCF is called.
Constraint: LDP≥M.
12:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, CALPUT=value was an illegal value.
IFAIL=2
On entry, M=value.
Constraint: M≥1.
IFAIL=3
On entry, N=value.
Constraint: N≥1.
IFAIL=4
On entry, X value=value.
Constraint: X i≥value and X i≤value.
IFAIL=5
On entry, S=value.
Constraint: S≥value and S≤value.
IFAIL=6
On entry, T value=value.
Constraint: T i≥value.
IFAIL=7
On entry, SIGMA=value.
Constraint: SIGMA>0.0.
IFAIL=8
On entry, R=value.
Constraint: R≥0.0.
IFAIL=9
On entry, Q=value.
Constraint: Q≥0.0.
IFAIL=11
On entry, LDP=value and M=value.
Constraint: LDP≥M.
IFAIL=14
On entry, S=value and β=value.
Constraint: Sβ<value.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The accuracy of the output will be bounded by the accuracy of the cumulative bivariate Normal distribution function. The algorithm of Genz (2004) is used, as described in the document for G01HAF, giving a maximum absolute error of less than 5×10-16. The univariate cumulative Normal distribution function also forms part of the evaluation (see S15ABF and S15ADF).

8 Parallelism and Performance

S30QCF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

None.

10 Example

This example computes the price of an American call with a time to expiry of 3 months, a stock price of 110 and a strike price of 100. The risk-free interest rate is 8% per year, there is an annual dividend return of 12% and the volatility is 20% per year.

10.1 Program Text

Program Text (s30qcfe.f90)

10.2 Program Data

Program Data (s30qcfe.d)

10.3 Program Results

Program Results (s30qcfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S30SAF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S30SAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S30SAF computes the Asian geometric continuous average-rate option price.

2 Specification

SUBROUTINE S30SAF ( CALPUT, M, N, X, S, T, SIGMA, R, B, P, LDP, IFAIL)
INTEGER | M, N, LDP, IFAIL
REAL (KIND=nag_wp) | X(M), S, T(N), SIGMA, R, B, P(LDP,N)
CHARACTER(1) | CALPUT

3 Description

S30SAF computes the price of an Asian geometric continuous average-rate option for constant volatility, σ, risk-free rate, r, and cost of carry, b (see Kemna and Vorst (1990)). For a given strike price, X, the price of a call option with underlying price, S, and time to expiry, T, is
Pcall = S e b--r T Φ d- 1 - X e-rT Φ d- 2 ,
and the corresponding put option price is
Pput = X e-rT Φ -d-2 - S e b--r T Φ - d-1 ,
where
d-1 = ln S/X + b- + σ-2 / 2 T σ- T
and
d-2 = d-1 - σ- T ,
with
σ- = σ 3 ,  b- = 1 2 r- σ 2 6 .
Φ is the cumulative Normal distribution function,
Φ x = 1 2 π ∫ -∞ x exp -y 2/2 dy .
The option price P ij=P X=Xi,T=Tj is computed for each strike price in a set Xi, i=1,2,…,m, and for each expiry time in a set Tj, j=1,2,…,n.

4 References

Kemna A and Vorst A (1990) A pricing method for options based on average asset values Journal of Banking and Finance 14 113–129

5 Arguments

1:   CALPUT – CHARACTER(1)Input
On entry: determines whether the option is a call or a put.
CALPUT='C'
A call; the holder has a right to buy.
CALPUT='P'
A put; the holder has a right to sell.
Constraint: CALPUT='C' or 'P'.
2:   M – INTEGERInput
On entry: the number of strike prices to be used.
Constraint: M≥1.
3:   N – INTEGERInput
On entry: the number of times to expiry to be used.
Constraint: N≥1.
4:   X M – REAL (KIND=nag_wp) arrayInput
On entry: X i must contain Xi, the ith strike price, for i=1,2,…,M.
Constraint: X i≥z ​ and ​ X i ≤ 1 / z , where z = X02AMF , the safe range parameter, for i=1,2,…,M.
5:   S – REAL (KIND=nag_wp)Input
On entry: S, the price of the underlying asset.
Constraint: S≥z ​ and ​S≤1.0/z, where z=X02AMF, the safe range parameter.
6:   T N – REAL (KIND=nag_wp) arrayInput
On entry: T i must contain Ti, the ith time, in years, to expiry, for i=1,2,…,N.
Constraint: T i≥z, where z = X02AMF , the safe range parameter, for i=1,2,…,N.
7:   SIGMA – REAL (KIND=nag_wp)Input
On entry: σ, the volatility of the underlying asset. Note that a rate of 15% should be entered as 0.15.
Constraint: SIGMA>0.0.
8:   R – REAL (KIND=nag_wp)Input
On entry: r, the annual risk-free interest rate, continuously compounded. Note that a rate of 5% should be entered as 0.05.
Constraint: R≥0.0.
9:   B – REAL (KIND=nag_wp)Input
On entry: b, the annual cost of carry rate. Note that a rate of 8% should be entered as 0.08.
10:   P LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: P ij contains P ij, the option price evaluated for the strike price Xi at expiry Tj for i=1,2,…,M and j=1,2,…,N.
11:   LDP – INTEGERInput
On entry: the first dimension of the array P as declared in the (sub)program from which S30SAF is called.
Constraint: LDP≥M.
12:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, CALPUT=value was an illegal value.
IFAIL=2
On entry, M=value.
Constraint: M≥1.
IFAIL=3
On entry, N=value.
Constraint: N≥1.
IFAIL=4
On entry, X value=value.
Constraint: X i≥value and X i≤value.
IFAIL=5
On entry, S=value.
Constraint: S≥value and S≤value.
IFAIL=6
On entry, T value=value.
Constraint: T i≥value.
IFAIL=7
On entry, SIGMA=value.
Constraint: SIGMA>0.0.
IFAIL=8
On entry, R=value.
Constraint: R≥0.0.
IFAIL=11
On entry, LDP=value and M=value.
Constraint: LDP≥M.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The accuracy of the output is dependent on the accuracy of the cumulative Normal distribution function, Φ. This is evaluated using a rational Chebyshev expansion, chosen so that the maximum relative error in the expansion is of the order of the machine precision (see S15ABF and S15ADF). An accuracy close to machine precision can generally be expected.

8 Parallelism and Performance

S30SAF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

None.

10 Example

This example computes the price of an Asian geometric continuous average-rate put with a time to expiry of 3 months, a stock price of 80 and a strike price of 85. The risk-free interest rate is 5% per year, the cost of carry is 8% and the volatility is 20% per year.

10.1 Program Text

Program Text (s30safe.f90)

10.2 Program Data

Program Data (s30safe.d)

10.3 Program Results

Program Results (s30safe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S30SBF : NAG Library, Mark 26

S Chapter Contents
S Chapter Introduction
NAG Library Manual

NAG Library Routine Document

S30SBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

S30SBF computes the Asian geometric continuous average-rate option price together with its sensitivities (Greeks).

2 Specification

SUBROUTINE S30SBF ( CALPUT, M, N, X, S, T, SIGMA, R, B, P, LDP, DELTA, GAMMA, VEGA, THETA, RHO, CRHO, VANNA, CHARM, SPEED, COLOUR, ZOMMA, VOMMA, IFAIL)
INTEGER | M, N, LDP, IFAIL
REAL (KIND=nag_wp) | X(M), S, T(N), SIGMA, R, B, P(LDP,N), DELTA(LDP,N), GAMMA(LDP,N), VEGA(LDP,N), THETA(LDP,N), RHO(LDP,N), CRHO(LDP,N), VANNA(LDP,N), CHARM(LDP,N), SPEED(LDP,N), COLOUR(LDP,N), ZOMMA(LDP,N), VOMMA(LDP,N)
CHARACTER(1) | CALPUT

3 Description

S30SBF computes the price of an Asian geometric continuous average-rate option, together with the Greeks or sensitivities, which are the partial derivatives of the option price with respect to certain of the other input parameters. The annual volatility, σ, risk-free rate, r, and cost of carry, b, are constants (see Kemna and Vorst (1990)). For a given strike price, X, the price of a call option with underlying price, S, and time to expiry, T, is
Pcall = S e b--r T Φ d- 1 - X e-rT Φ d- 2 ,
and the corresponding put option price is
Pput = X e-rT Φ -d-2 - S e b--r T Φ - d-1 ,
where
d-1 = ln S/X + b- + σ-2 / 2 T σ- T
and
d-2 = d-1 - σ- T ,
with
σ- = σ 3 ,  b- = 1 2 b- σ 2 6 .
Φ is the cumulative Normal distribution function,
Φ x = 1 2 π ∫ -∞ x exp -y 2/2 dy .
The option price P ij=P X=Xi,T=Tj is computed for each strike price in a set Xi, i=1,2,…,m, and for each expiry time in a set Tj, j=1,2,…,n.

4 References

Kemna A and Vorst A (1990) A pricing method for options based on average asset values Journal of Banking and Finance 14 113–129

5 Arguments

1:   CALPUT – CHARACTER(1)Input
On entry: determines whether the option is a call or a put.
CALPUT='C'
A call; the holder has a right to buy.
CALPUT='P'
A put; the holder has a right to sell.
Constraint: CALPUT='C' or 'P'.
2:   M – INTEGERInput
On entry: the number of strike prices to be used.
Constraint: M≥1.
3:   N – INTEGERInput
On entry: the number of times to expiry to be used.
Constraint: N≥1.
4:   X M – REAL (KIND=nag_wp) arrayInput
On entry: X i must contain Xi, the ith strike price, for i=1,2,…,M.
Constraint: X i≥z ​ and ​ X i ≤ 1 / z , where z = X02AMF , the safe range parameter, for i=1,2,…,M.
5:   S – REAL (KIND=nag_wp)Input
On entry: S, the price of the underlying asset.
Constraint: S≥z ​ and ​S≤1.0/z, where z=X02AMF, the safe range parameter.
6:   T N – REAL (KIND=nag_wp) arrayInput
On entry: T i must contain Ti, the ith time, in years, to expiry, for i=1,2,…,N.
Constraint: T i≥z, where z = X02AMF , the safe range parameter, for i=1,2,…,N.
7:   SIGMA – REAL (KIND=nag_wp)Input
On entry: σ, the volatility of the underlying asset. Note that a rate of 15% should be entered as 0.15.
Constraint: SIGMA>0.0.
8:   R – REAL (KIND=nag_wp)Input
On entry: r, the annual risk-free interest rate, continuously compounded. Note that a rate of 5% should be entered as 0.05.
Constraint: R≥0.0.
9:   B – REAL (KIND=nag_wp)Input
On entry: b, the annual cost of carry rate. Note that a rate of 8% should be entered as 0.08.
10:   P LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: P ij contains P ij, the option price evaluated for the strike price Xi at expiry Tj for i=1,2,…,M and j=1,2,…,N.
11:   LDP – INTEGERInput
On entry: the first dimension of the arrays P, DELTA, GAMMA, VEGA, THETA, RHO, CRHO, VANNA, CHARM, SPEED, COLOUR, ZOMMA and VOMMA as declared in the (sub)program from which S30SBF is called.
Constraint: LDP≥M.
12:   DELTA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: the leading M×N part of the array DELTA contains the sensitivity, ∂P∂S, of the option price to change in the price of the underlying asset.
13:   GAMMA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: the leading M×N part of the array GAMMA contains the sensitivity, ∂2 P∂S 2, of DELTA to change in the price of the underlying asset.
14:   VEGA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: VEGA ij, contains the first-order Greek measuring the sensitivity of the option price P ij to change in the volatility of the underlying asset, i.e., ∂P ij ∂σ , for i=1,2,…,M and j=1,2,…,N.
15:   THETA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: THETA ij, contains the first-order Greek measuring the sensitivity of the option price P ij to change in time, i.e., - ∂P ij ∂T , for i=1,2,…,M and j=1,2,…,N, where b=r-q.
16:   RHO LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: RHO ij, contains the first-order Greek measuring the sensitivity of the option price P ij to change in the annual risk-free interest rate, i.e., - ∂P ij ∂r , for i=1,2,…,M and j=1,2,…,N.
17:   CRHO LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: DELTA ij, contains the first-order Greek measuring the sensitivity of the option price P ij to change in the price of the underlying asset, i.e., - ∂P ij ∂S , for i=1,2,…,M and j=1,2,…,N.
18:   VANNA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: VANNA ij, contains the second-order Greek measuring the sensitivity of the first-order Greek Δ ij to change in the volatility of the asset price, i.e., - ∂Δ ij ∂T = - ∂2 P ij ∂S∂σ , for i=1,2,…,M and j=1,2,…,N.
19:   CHARM LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: CHARM ij, contains the second-order Greek measuring the sensitivity of the first-order Greek Δ ij to change in the time, i.e., - ∂Δ ij ∂T = - ∂2 P ij ∂S∂T , for i=1,2,…,M and j=1,2,…,N.
20:   SPEED LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: SPEED ij, contains the third-order Greek measuring the sensitivity of the second-order Greek Γ ij to change in the price of the underlying asset, i.e., - ∂Γ ij ∂S = - ∂3 P ij ∂S 3 , for i=1,2,…,M and j=1,2,…,N.
21:   COLOUR LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: COLOUR ij, contains the third-order Greek measuring the sensitivity of the second-order Greek Γ ij to change in the time, i.e., - ∂Γ ij ∂T = - ∂3 P ij ∂S∂T , for i=1,2,…,M and j=1,2,…,N.
22:   ZOMMA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: ZOMMA ij, contains the third-order Greek measuring the sensitivity of the second-order Greek Γ ij to change in the volatility of the underlying asset, i.e., - ∂Γ ij ∂σ = - ∂3 P ij ∂S 2∂σ , for i=1,2,…,M and j=1,2,…,N.
23:   VOMMA LDPN – REAL (KIND=nag_wp) arrayOutput
On exit: VOMMA ij, contains the second-order Greek measuring the sensitivity of the first-order Greek Δ ij to change in the volatility of the underlying asset, i.e., - ∂Δ ij ∂σ = - ∂2 P ij ∂σ 2 , for i=1,2,…,M and j=1,2,…,N.
24:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, CALPUT=value was an illegal value.
IFAIL=2
On entry, M=value.
Constraint: M≥1.
IFAIL=3
On entry, N=value.
Constraint: N≥1.
IFAIL=4
On entry, X value=value.
Constraint: X i≥value and X i≤value.
IFAIL=5
On entry, S=value.
Constraint: S≥value and S≤value.
IFAIL=6
On entry, T value=value.
Constraint: T i≥value.
IFAIL=7
On entry, SIGMA=value.
Constraint: SIGMA>0.0.
IFAIL=8
On entry, R=value.
Constraint: R≥0.0.
IFAIL=11
On entry, LDP=value and M=value.
Constraint: LDP≥M.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

The accuracy of the output is dependent on the accuracy of the cumulative Normal distribution function, Φ. This is evaluated using a rational Chebyshev expansion, chosen so that the maximum relative error in the expansion is of the order of the machine precision (see S15ABF and S15ADF). An accuracy close to machine precision can generally be expected.

8 Parallelism and Performance

S30SBF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

None.

10 Example

This example computes the price of an Asian geometric continuous average-rate call with a time to expiry of 3 months, a stock price of 80 and a strike price of 97. The risk-free interest rate is 5% per year, the cost of carry is 8% and the volatility is 20% per year.

10.1 Program Text

Program Text (s30sbfe.f90)

10.2 Program Data

Program Data (s30sbfe.d)

10.3 Program Results

Program Results (s30sbfe.r)

S Chapter Contents
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S Chapter Contents : NAG Library Manual, Mark 26

S Chapter Introduction

NAG Library Chapter Contents

S – Approximations of Special Functions

S Chapter Introduction – a description of the Chapter and an overview of the algorithms available

Routine Name | Mark of Introduction | Purpose
S01BAF Example Text Example Data | 14 | nagf_specfun_log_shifted ln 1+x
S01EAF Example Text Example Data | 14 | nagf_specfun_exp_complex Complex exponential, ez
S07AAF Example Text Example Data | 1 | nagf_specfun_tan tan⁡x
S09AAF Example Text Example Data | 1 | nagf_specfun_arcsin arcsin⁡x
S09ABF Example Text Example Data | 3 | nagf_specfun_arccos arccos⁡x
S10AAF Example Text Example Data | 3 | nagf_specfun_tanh tanh⁡x
S10ABF Example Text Example Data | 4 | nagf_specfun_sinh sinh⁡x
S10ACF Example Text Example Data | 4 | nagf_specfun_cosh cosh⁡x
S11AAF Example Text Example Data | 4 | nagf_specfun_arctanh arctanh⁡x
S11ABF Example Text Example Data | 4 | nagf_specfun_arcsinh arcsinh⁡x
S11ACF Example Text Example Data | 4 | nagf_specfun_arccosh arccosh⁡x
S13AAF Example Text Example Data Example Plot | 1 | nagf_specfun_integral_exp Exponential integral E 1 x
S13ACF Example Text Example Data Example Plot | 2 | nagf_specfun_integral_cos Cosine integral Ci x
S13ADF Example Text Example Data Example Plot | 5 | nagf_specfun_integral_sin Sine integral Si x
S14AAF Example Text Example Data Example Plot | 1 | nagf_specfun_gamma Gamma function
S14ABF Example Text Example Data Example Plot | 8 | nagf_specfun_gamma_log_real Log gamma function, real argument
S14ACF Example Text Example Data Example Plot | 14 | nagf_specfun_polygamma ψ x-ln⁡x
S14ADF Example Text Example Data | 14 | nagf_specfun_polygamma_deriv Scaled derivatives of ψ x
S14AEF Example Text Example Data | 20 | nagf_specfun_psi_deriv_real Polygamma function ψ n x for real x
S14AFF Example Text Example Data | 20 | nagf_specfun_psi_deriv_complex Polygamma function ψ n z for complex z
S14AGF Example Text Example Data | 21 | nagf_specfun_gamma_log_complex Logarithm of the gamma function ln⁡Γ z, complex argument
S14AHF Example Text Example Data Example Plot | 23 | nagf_specfun_gamma_log_scaled_real Scaled log gamma function
S14BAF Example Text Example Data Example Plot | 14 | nagf_specfun_gamma_incomplete Incomplete gamma functions P a,x and Q a,x
S14CBF Example Text Example Data | 24 | nagf_specfun_beta_log_real Logarithm of the beta function ln⁡B a,b
S14CCF Example Text Example Data | 24 | nagf_specfun_beta_incomplete Incomplete beta function Ix a,b and its complement 1-Ix
S15ABF Example Text Example Data | 3 | nagf_specfun_cdf_normal Cumulative Normal distribution function P x
S15ACF Example Text Example Data | 4 | nagf_specfun_compcdf_normal Complement of cumulative Normal distribution function Q x
S15ADF Example Text Example Data | 4 | nagf_specfun_erfc_real Complement of error function erfc x
S15AEF Example Text Example Data | 4 | nagf_specfun_erf_real Error function erf x
S15AFF Example Text Example Data | 7 | nagf_specfun_dawson Dawson's integral
S15AGF Example Text Example Data | 22 | nagf_specfun_erfcx_real Scaled complement of error function, erfcx x
S15DDF Example Text Example Data | 14 | nagf_specfun_erfc_complex Scaled complex complement of error function, exp-z 2erfc-iz
S17ACF Example Text Example Data Example Plot | 1 | nagf_specfun_bessel_y0_real Bessel function Y 0 x
S17ADF Example Text Example Data Example Plot | 1 | nagf_specfun_bessel_y1_real Bessel function Y 1 x
S17AEF Example Text Example Data Example Plot | 5 | nagf_specfun_bessel_j0_real Bessel function J 0 x
S17AFF Example Text Example Data Example Plot | 5 | nagf_specfun_bessel_j1_real Bessel function J 1 x
S17AGF Example Text Example Data Example Plot | 8 | nagf_specfun_airy_ai_real Airy function Ai x
S17AHF Example Text Example Data Example Plot | 8 | nagf_specfun_airy_bi_real Airy function Bi x
S17AJF Example Text Example Data Example Plot | 8 | nagf_specfun_airy_ai_deriv Airy function Ai′x
S17AKF Example Text Example Data Example Plot | 8 | nagf_specfun_airy_bi_deriv Airy function Bi′x
S17ALF Example Text Example Data | 20 | nagf_specfun_bessel_zeros Zeros of Bessel functions Jα x, Jα′x, Yα x or Yα′x
S17AQF Example Text Example Data | 24 | nagf_specfun_bessel_y0_real_vector Bessel function vectorized Y 0 x
S17ARF Example Text Example Data | 24 | nagf_specfun_bessel_y1_real_vector Bessel function vectorized Y 1 x
S17ASF Example Text Example Data | 24 | nagf_specfun_bessel_j0_real_vector Bessel function vectorized J 0 x
S17ATF Example Text Example Data | 24 | nagf_specfun_bessel_j1_real_vector Bessel function vectorized J 1 x
S17AUF Example Text Example Data | 24 | nagf_specfun_airy_ai_real_vector Airy function vectorized Ai x
S17AVF Example Text Example Data | 24 | nagf_specfun_airy_bi_real_vector Airy function vectorized Bi x
S17AWF Example Text Example Data | 24 | nagf_specfun_airy_ai_deriv_vector Derivatives of the Airy function, vectorized Ai′x
S17AXF Example Text Example Data | 24 | nagf_specfun_airy_bi_deriv_vector Derivatives of the Airy function, vectorized Bi′x
S17DCF Example Text Example Data | 13 | nagf_specfun_bessel_y_complex Bessel functions Y ν+a z, real a≥0, complex z, ν=0,1,2,…
S17DEF Example Text Example Data | 13 | nagf_specfun_bessel_j_complex Bessel functions J ν+a z, real a≥0, complex z, ν=0,1,2,…
S17DGF Example Text Example Data | 13 | nagf_specfun_airy_ai_complex Airy functions Ai z and Ai′z, complex z
S17DHF Example Text Example Data | 13 | nagf_specfun_airy_bi_complex Airy functions Bi z and Bi′z, complex z
S17DLF Example Text Example Data | 13 | nagf_specfun_hankel_complex Hankel functions H ν+a j z, j=1,2, real a≥0, complex z, ν=0,1,2,…
S18ACF Example Text Example Data Example Plot | 1 | nagf_specfun_bessel_k0_real Modified Bessel function K 0 x
S18ADF Example Text Example Data Example Plot | 1 | nagf_specfun_bessel_k1_real Modified Bessel function K 1 x
S18AEF Example Text Example Data Example Plot | 5 | nagf_specfun_bessel_i0_real Modified Bessel function I 0 x
S18AFF Example Text Example Data Example Plot | 5 | nagf_specfun_bessel_i1_real Modified Bessel function I 1 x
S18AQF Example Text Example Data | 24 | nagf_specfun_bessel_k0_real_vector Modified Bessel function vectorized K 0 x
S18ARF Example Text Example Data | 24 | nagf_specfun_bessel_k1_real_vector Modified Bessel function vectorized K 1 x
S18ASF Example Text Example Data | 24 | nagf_specfun_bessel_i0_real_vector Modified Bessel function vectorized I 0 x
S18ATF Example Text Example Data | 24 | nagf_specfun_bessel_i1_real_vector Modified Bessel function vectorized I 1 x
S18CCF Example Text Example Data | 10 | nagf_specfun_bessel_k0_scaled Scaled modified Bessel function ex K 0 x
S18CDF Example Text Example Data | 10 | nagf_specfun_bessel_k1_scaled Scaled modified Bessel function ex K 1 x
S18CEF Example Text Example Data | 10 | nagf_specfun_bessel_i0_scaled Scaled modified Bessel function e-x I 0 x
S18CFF Example Text Example Data | 10 | nagf_specfun_bessel_i1_scaled Scaled modified Bessel function e-x I 1 x
S18CQF Example Text Example Data | 24 | nagf_specfun_bessel_k0_scaled_vector Scaled modified Bessel function vectorized ex K 0 x
S18CRF Example Text Example Data | 24 | nagf_specfun_bessel_k1_scaled_vector Scaled modified Bessel function vectorized ex K 1 x
S18CSF Example Text Example Data | 24 | nagf_specfun_bessel_i0_scaled_vector Scaled modified Bessel function vectorized e-x I 0 x
S18CTF Example Text Example Data | 24 | nagf_specfun_bessel_i1_scaled_vector Scaled modified Bessel function vectorized e-x I 1 x
S18DCF Example Text Example Data | 13 | nagf_specfun_bessel_k_complex Modified Bessel functions K ν+a z, real a≥0, complex z, ν=0,1,2,…
S18DEF Example Text Example Data | 13 | nagf_specfun_bessel_i_complex Modified Bessel functions I ν+a z, real a≥0, complex z, ν=0,1,2,…
S18GKF Example Text Example Data | 21 | nagf_specfun_bessel_j_seq_complex Bessel function of the 1st kind J α±n z
S19AAF Example Text Example Data | 11 | nagf_specfun_kelvin_ber Kelvin function ber⁡x
S19ABF Example Text Example Data | 11 | nagf_specfun_kelvin_bei Kelvin function bei⁡x
S19ACF Example Text Example Data | 11 | nagf_specfun_kelvin_ker Kelvin function ker⁡x
S19ADF Example Text Example Data | 11 | nagf_specfun_kelvin_kei Kelvin function kei⁡x
S19ANF Example Text Example Data | 24 | nagf_specfun_kelvin_ber_vector Kelvin function vectorized ber⁡x
S19APF Example Text Example Data | 24 | nagf_specfun_kelvin_bei_vector Kelvin function vectorized bei⁡x
S19AQF Example Text Example Data | 24 | nagf_specfun_kelvin_ker_vector Kelvin function vectorized ker⁡x
S19ARF Example Text Example Data | 24 | nagf_specfun_kelvin_kei_vector Kelvin function vectorized kei⁡x
S20ACF Example Text Example Data Example Plot | 5 | nagf_specfun_fresnel_s Fresnel integral S x
S20ADF Example Text Example Data Example Plot | 5 | nagf_specfun_fresnel_c Fresnel integral C x
S20AQF Example Text Example Data | 24 | nagf_specfun_fresnel_s_vector Fresnel integral vectorized S x
S20ARF Example Text Example Data | 24 | nagf_specfun_fresnel_c_vector Fresnel integral vectorized C x
S21BAF Example Text | 8 | nagf_specfun_ellipint_symm_1_degen Degenerate symmetrised elliptic integral of 1st kind RC x,y
S21BBF Example Text | 8 | nagf_specfun_ellipint_symm_1 Symmetrised elliptic integral of 1st kind RF x,y,z
S21BCF Example Text | 8 | nagf_specfun_ellipint_symm_2 Symmetrised elliptic integral of 2nd kind RD x,y,z
S21BDF Example Text | 8 | nagf_specfun_ellipint_symm_3 Symmetrised elliptic integral of 3rd kind RJ x,y,z,r
S21BEF Example Text Example Plot | 22 | nagf_specfun_ellipint_legendre_1 Elliptic integral of 1st kind, Legendre form, F ϕ∣m
S21BFF Example Text Example Plot | 22 | nagf_specfun_ellipint_legendre_2 Elliptic integral of 2nd kind, Legendre form, E ϕ∣m
S21BGF Example Text | 22 | nagf_specfun_ellipint_legendre_3 Elliptic integral of 3rd kind, Legendre form, Π n;ϕ∣m
S21BHF Example Text | 22 | nagf_specfun_ellipint_complete_1 Complete elliptic integral of 1st kind, Legendre form, K m
S21BJF Example Text | 22 | nagf_specfun_ellipint_complete_2 Complete elliptic integral of 2nd kind, Legendre form, E m
S21CAF Example Text Example Data | 15 | nagf_specfun_jacellip_real Jacobian elliptic functions sn, cn and dn of real argument
S21CBF Example Text Example Data | 20 | nagf_specfun_jacellip_complex Jacobian elliptic functions sn, cn and dn of complex argument
S21CCF Example Text Example Data | 20 | nagf_specfun_jactheta_real Jacobian theta functions θk x,q of real argument
S21DAF Example Text Example Data | 20 | nagf_specfun_ellipint_general_2 General elliptic integral of 2nd kind F z,k′,a,b of complex argument
S22AAF Example Text Example Data | 20 | nagf_specfun_legendre_p Legendre functions of 1st kind Pnm x or Pnm¯x
S22BAF Example Text | 24 | nagf_specfun_1f1_real Real confluent hypergeometric function F 1 1 a;b;x
S22BBF Example Text | 24 | nagf_specfun_1f1_real_scaled Real confluent hypergeometric function F 1 1 a;b;x in scaled form
S22BEF Example Text | 25 | nagf_specfun_2f1_real Real Gauss hypergeometric function F 1 2 a,b;c;x
S22BFF Example Text | 25 | nagf_specfun_2f1_real_scaled Real Gauss hypergeometric function F 1 2 a,b; c;x in scaled form.
S30AAF Example Text Example Data | 22 | nagf_specfun_opt_bsm_price Black–Scholes–Merton option pricing formula
S30ABF Example Text Example Data | 22 | nagf_specfun_opt_bsm_greeks Black–Scholes–Merton option pricing formula with Greeks
S30BAF Example Text Example Data | 22 | nagf_specfun_opt_lookback_fls_price Floating-strike lookback option pricing formula in the Black-Scholes-Merton model
S30BBF Example Text Example Data | 22 | nagf_specfun_opt_lookback_fls_greeks Floating-strike lookback option pricing formula with Greeks in the Black-Scholes-Merton model
S30CAF Example Text Example Data | 22 | nagf_specfun_opt_binary_con_price Binary option, cash-or-nothing pricing formula
S30CBF Example Text Example Data | 22 | nagf_specfun_opt_binary_con_greeks Binary option, cash-or-nothing pricing formula with Greeks
S30CCF Example Text Example Data | 22 | nagf_specfun_opt_binary_aon_price Binary option, asset-or-nothing pricing formula
S30CDF Example Text Example Data | 22 | nagf_specfun_opt_binary_aon_greeks Binary option, asset-or-nothing pricing formula with Greeks
S30FAF Example Text Example Data | 22 | nagf_specfun_opt_barrier_std_price Standard barrier option pricing formula
S30JAF Example Text Example Data | 22 | nagf_specfun_opt_jumpdiff_merton_price Jump-diffusion, Merton's model, option pricing formula
S30JBF Example Text Example Data | 22 | nagf_specfun_opt_jumpdiff_merton_greeks Jump-diffusion, Merton's model, option pricing formula with Greeks
S30NAF Example Text Example Data | 22 | nagf_specfun_opt_heston_price Heston's model option pricing formula
S30NBF Example Text Example Data | 23 | nagf_specfun_opt_heston_greeks Heston's model option pricing formula with Greeks
S30NCF Example Text Example Data | 25 | nagf_specfun_opt_heston_term Heston's model option pricing with term structure
S30QCF Example Text Example Data | 22 | nagf_specfun_opt_amer_bs_price American option, Bjerksund and Stensland pricing formula
S30SAF Example Text Example Data | 22 | nagf_specfun_opt_asian_geom_price Asian option, geometric continuous average rate pricing formula
S30SBF Example Text Example Data | 22 | nagf_specfun_opt_asian_geom_greeks Asian option, geometric continuous average rate pricing formula with Greeks
S Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


S Chapter Introduction : NAG Library, Mark 26

S Chapter Contents

NAG Library Chapter Introduction

S – Approximations of Special Functions

▸▿ Contents

1 Scope of the Chapter
▸▿ 2 Background to the Problems
2.1 Functions of a Single Real Argument
2.2 Approximations to Elliptic Integrals
2.3 Bessel and Airy Functions of a Complex Argument
▸▿ 2.4 Option Pricing Routines
2.4.1 The Black–Scholes Model
2.4.2 The Black–Scholes Model with Term Structure
2.4.3 The Heston Model
2.4.4 The Heston Model with Term Structure
2.5 Hypergeometric Functions
▸▿ 3 Recommendations on Choice and Use of Available Routines
3.1 Vectorized Routine Variants
3.2 Elliptic Integrals
3.3 Bessel and Airy Functions
3.4 Option Pricing Functions
3.5 Hypergeometric Functions
4 Functionality Index
5 Auxiliary Routines Associated with Library Routine Arguments
6 Routines Withdrawn or Scheduled for Withdrawal
7 References

1 Scope of the Chapter

This chapter is concerned with the provision of some commonly occurring physical and mathematical functions.

2 Background to the Problems

The majority of the routines in this chapter approximate real-valued functions of a single real argument, and the techniques involved are described in Section 2.1. In addition the chapter contains routines for elliptic integrals (see Section 2.2), Bessel and Airy functions of a complex argument (see Section 2.3), complementary error function of a complex argument, hypergeometric functions and various option pricing routines for use in financial applications.

2.1 Functions of a Single Real Argument

Most of the routines provided for functions of a single real argument have been based on truncated Chebyshev expansions. This method of approximation was adopted as a compromise between the conflicting requirements of efficiency and ease of implementation on many different machine ranges. For details of the reasons behind this choice and the production and testing procedures followed in constructing this chapter see Schonfelder (1976).
Basically, if the function to be approximated is f x, then for x∈a,b an approximation of the form
f x=g x∑′r=0 CrTr t
is used (∑′ denotes, according to the usual convention, a summation in which the first term is halved), where g x is some suitable auxiliary function which extracts any singularities, asymptotes and, if possible, zeros of the function in the range in question and t=t x is a mapping of the general range a,b to the specific range [-1,+1] required by the Chebyshev polynomials, Tr t. For a detailed description of the properties of the Chebyshev polynomials see Clenshaw (1962) and Fox and Parker (1968).
The essential property of these polynomials for the purposes of function approximation is that Tn t oscillates between ±1 and it takes its extreme values n+1 times in the interval [-1,+1]. Therefore, provided the coefficients Cr decrease in magnitude sufficiently rapidly the error made by truncating the Chebyshev expansion after n terms is approximately given by
E t≃CnTn t.
That is, the error oscillates between ±Cn and takes its extreme value n+1 times in the interval in question. Now this is just the condition that the approximation be a minimax representation, one which minimizes the maximum error. By suitable choice of the interval, [a,b], the auxiliary function, g x, and the mapping of the independent variable, t x, it is almost always possible to obtain a Chebyshev expansion with rapid convergence and hence truncations that provide near minimax polynomial approximations to the required function. The difference between the true minimax polynomial and the truncated Chebyshev expansion is seldom sufficiently great enough to be of significance.
The evaluation of the Chebyshev expansions follows one of two methods. The first and most efficient, and hence the most commonly used, works with the equivalent simple polynomial. The second method, which is used on the few occasions when the first method proves to be unstable, is based directly on the truncated Chebyshev series, and uses backward recursion to evaluate the sum. For the first method, a suitably truncated Chebyshev expansion (truncation is chosen so that the error is less than the machine precision) is converted to the equivalent simple polynomial. That is, we evaluate the set of coefficients br such that
y t=∑r=0 n-1 br tr=∑′r=0 n-1 CrTr t.
The polynomial can then be evaluated by the efficient Horner's method of nested multiplications,
y t=b 0+t b 1+t b 2+…t b n- 2+t b n- 1….
This method of evaluation results in efficient routines but for some expansions there is considerable loss of accuracy due to cancellation effects. In these cases the second method is used. It is well known that if
b n-1=C n-1 b n-2=2 t b n-1+C n-2 b j-0=2 t b j+1-b j+2+Cj,  j=n-3,n-4,…,0
then
∑′r=0 CrTr t=12 b 0-b 2
and this is always stable. This method is most efficiently implemented by using three variables cyclically and explicitly constructing the recursion.
That is,
α = C n-1 β = 2 tα+C n-2 γ = 2 tβ-α+C n-3 α = 2 tγ-β+C n-4 β = 2 tα-γ+C n-5 ⋮ say ​α = 2 tγ-β+C 2 β = 2 tα-γ+C 1 y t = tβ-α+12 C 0
The auxiliary functions used are normally functions compounded of simple polynomial (usually linear) factors extracting zeros, and the primary compiler-provided functions, sin, cos, ln, exp, sqrt, which extract singularities and/or asymptotes or in some cases basic oscillatory behaviour, leaving a smooth well-behaved function to be approximated by the Chebyshev expansion which can therefore be rapidly convergent.
The mappings of [a,b] to [-1,+1] used range from simple linear mappings to the case when b is infinite, and considerable improvement in convergence can be obtained by use of a bilinear form of mapping. Another common form of mapping is used when the function is even; that is, it involves only even powers in its expansion. In this case an approximation over the whole interval [-a,a] can be provided using a mapping t=2 x/a 2-1. This embodies the evenness property but the expansion in t involves all powers and hence removes the necessity of working with an expansion with half its coefficients zero.
For many of the routines an analysis of the error in principle is given, namely, if E and ∇ are the absolute errors in function and argument and ε and δ are the corresponding relative errors, then
E ≃ f′x∇ E ≃ x f′x δ ε ≃ x f′ x f x δ.
If we ignore errors that arise in the argument of the function by propagation of data errors, etc., and consider only those errors that result from the fact that a real number is being represented in the computer in floating-point form with finite precision, then δ is bounded and this bound is independent of the magnitude of x. For example, on an 11-digit machine
δ≤10-11.
(This of course implies that the absolute error ∇=xδ is also bounded but the bound is now dependent on x.) However, because of this the last two relations above are probably of more interest. If possible the relative error propagation is discussed; that is, the behaviour of the error amplification factor x f′x/f x is described, but in some cases, such as near zeros of the function which cannot be extracted explicitly, absolute error in the result is the quantity of significance and here the factor x f′x is described. In general, testing of the functions has shown that their error behaviour follows fairly well these theoretical error behaviours. In regions where the error amplification factors are less than or of the order of one, the errors are slightly larger than the above predictions. The errors are here limited largely by the finite precision of arithmetic in the machine, but ε is normally no more than a few times greater than the bound on δ. In regions where the amplification factors are large, of order ten or greater, the theoretical analysis gives a good measure of the accuracy obtainable.
It should be noted that the definitions and notations used for the functions in this chapter are all taken from Abramowitz and Stegun (1972). You are strongly recommended to consult this book for details before using the routines in this chapter.

2.2 Approximations to Elliptic Integrals

Four functions provided here are symmetrised variants of the classical (Legendre) elliptic integrals. These alternative definitions have been suggested by Carlson (1965), Carlson (1977b) and Carlson (1977a) and he also developed the basic algorithms used in this chapter.
The symmetrised elliptic integral of the first kind is represented by
RF x,y,z = 12 ∫0∞ dt t+x t+y t+z ,
where x,y,z≥0 and at most one may be equal to zero.
The normalization factor, 12 , is chosen so as to make
RF x,x,x=1/x.
If any two of the variables are equal, RF degenerates into the second function
RC x,y = RF x,y,y = 12 ∫0∞ dt t+y . t+x ,
where the argument restrictions are now x≥0 and y≠0.
This function is related to the logarithm or inverse hyperbolic functions if 0<y<x, and to the inverse circular functions if 0≤x≤y.
The symmetrised elliptic integral of the second kind is defined by
RD x,y,z = 32 ∫0∞ dt t+x t+y t+z 3
with z>0, x≥0 and y≥0, but only one of x or y may be zero.
The function is a degenerate special case of the symmetrised elliptic integral of the third kind
RJ x,y,z,ρ = 32 ∫0∞ dt t+x t+y t+z t+ρ
with ρ≠0 and x,y,z≥0 with at most one equality holding. Thus RD x,y,z=RJ x,y,z,z. The normalization of both these functions is chosen so that
RD x,x,x=RJ x,x,x,x=1/x⁢x.
The algorithms used for all these functions are based on duplication theorems. These allow a recursion system to be established which constructs a new set of arguments from the old using a combination of arithmetic and geometric means. The value of the function at the original arguments can then be simply related to the value at the new arguments. These recursive reductions are used until the arguments differ from the mean by an amount small enough for a Taylor series about the mean to give sufficient accuracy when retaining terms of order less than six. Each step of the recurrences reduces the difference from the mean by a factor of four, and as the truncation error is of order six, the truncation error goes like 4096-n, where n is the number of iterations.
The above forms can be related to the more traditional canonical forms (see Section 17.2 of Abramowitz and Stegun (1972)), as follows.
If we write q=cos 2⁡ϕ, r=1-m sin 2⁡ϕ, s=1-n sin 2⁡ϕ , where 0≤ϕ≤12 π , we have
the classical elliptic integral of the first kind:
F ϕ∣m = ∫0 ϕ 1-m   sin 2⁡θ -12 dθ = sin⁡ϕ   RF q,r,1 ;
the classical elliptic integral of the second kind:
E ϕ∣m = ∫0 ϕ 1-m   sin 2⁡θ 12 dθ = sin⁡ϕ   RF q,r,1 -13 m   sin 3 ϕ   RD q,r,1
the classical elliptic integral of the third kind:
Π n; ϕ∣m = ∫0 ϕ 1-n   sin 2⁡θ -1 1-m   sin 2⁡θ -12 dθ = sin⁡ϕ   RF q,r,1 + 13 n   sin 3 ϕ   RJ q,r,1,s .
Also the classical complete elliptic integral of the first kind:
K m = ∫ 0 π 2 1 - m   sin 2⁡θ -12 dθ = RF 0,1-m,1 ;
the classical complete elliptic integral of the second kind:
E m = ∫ 0 π 2 1-m   sin 2 θ 12 dθ = RF 0,1-m,1 - 13 m   RD 0,1-m,1 .
For convenience, Chapter S contains routines to evaluate classical and symmetrised elliptic integrals.

2.3 Bessel and Airy Functions of a Complex Argument

The routines for Bessel and Airy functions of a real argument are based on Chebyshev expansions, as described in Section 2.1. The routines provided for functions of a complex argument, however, use different methods. These routines relate all functions to the modified Bessel functions Iν z and Kν z computed in the right-half complex plane, including their analytic continuations. Iν and Kν are computed by different methods according to the values of z and ν. The methods include power series, asymptotic expansions and Wronskian evaluations. The relations between functions are based on well known formulae (see Abramowitz and Stegun (1972)).

2.4 Option Pricing Routines

The option pricing routines evaluate the closed form solutions or approximations to the equations that define mathematical models for the prices of selected financial option contracts. These solutions can be viewed as special functions determined by the underlying equations. The terminology associated with these routines arises from their setting in financial markets and is briefly outlined below. See Joshi (2003) for a comprehensive introduction to this subject. An option is a contract which gives the holder the right, but not the obligation, to buy (if it is a call) or sell (if it is a put) a particular asset, S. A European option can be exercised only at the specified expiry time, T, while an American option can be exercised at any time up to T. For Asian options the average underlying price over a pre-set time period determines the payoff.
The asset is bought (if a call) or sold (if a put) at a pre-specified strike price X. Thus, an option contract has a payoff to the holder of max ST-X,0 for a call or max X-ST,0, for a put, which depends on whether the asset price at the time of exercise is above (call) or below (put) the strike, X. If at any moment in time a contract is currently showing a theoretical profit then it is deemed ‘in-the-money’; otherwise it is deemed ‘out-of-the-money’.
The option contract itself therefore has a value and, in many cases, can be traded in markets. Mathematical models (e.g., Black–Scholes, Merton, Vasicek, Hull–White, Heston, CEV, SABR, …) give theoretical prices for particular option contracts using a number of assumptions about the behaviour of financial markets. Typically the price St of the underlying asset at time t is modelled as the solution of a stochastic differential equation (SDE). Depending on the complexity of this equation, the model may admit closed form formulae for the prices of various options. The options described in this chapter introduction are detailed below. We let 𝔼 denote expectation with respect to the risk neutral measure and we define 𝕀A to be 1 on the set A and 0 otherwise.
– The price of a standard European call option is 𝔼 e-rT max ST-X,0 and the price of a standard European put option is 𝔼 e-rT max X-ST,0.
– For continuously averaged geometric Asian options define
G T = exp ∫ 0 T log St dt .
Then the price of an Asian call option is 𝔼 e-rT max G T - X ,0 and the price of an Asian put option is 𝔼 e-rT max X- G T ,0 .
– For a binary asset-or-nothing option the price of a call is 𝔼 e-rT ST 𝕀 ST>X and the price of a put is 𝔼 e-rT ST 𝕀 ST<X .
– For a binary cash-or-nothing option the price of a call is 𝔼 e-rT X 𝕀 ST>X and the price of a put is 𝔼 e-rT X 𝕀 ST<X .
– For a floating-strike lookback option the price of a call is 𝔼 e-rT ST - min 0≤t≤T St and the price of a put is 𝔼 e-rT max 0≤t≤T St - ST .
– For an up-and-in barrier option with barrier level H and cash rebate K, set A = max 0≤t≤T St > H . Then the price of a call is
𝔼 e-rT max ST-X,0 𝕀A + e-rT K 1 - 𝕀A
and the price of a put is
𝔼 e-rT max X-ST,0 𝕀A+ e-rT K 1-𝕀A
– For a down-and-in barrier option with barrier level H and cash rebate K, set A = min 0≤t≤T St < H . Then the price of a call is
𝔼 e-rT max ST-X,0 𝕀A + e -rT K 1-𝕀A
and the price of a put is
𝔼 e-rT max⁡ X-ST,0 𝕀A + e-rT K 1-𝕀A
– For an up-and-out barrier option with barrier level H and cash rebate K, set A = max 0≤t≤T St >H . Then the price of a call is
𝔼 e-rT max ST-X,0 1-𝕀A + e-rT K 𝕀A
and the price of a put is
𝔼 e-rT max X-ST,0 1-𝕀A + e-rT K 𝕀A
– For a down-and-out barrier option with barrier level H and cash rebate K, set A = min 0≤t≤T St <H . Then the price of a call is
𝔼 e-rT max ST-X,0 1-𝕀A + e-rT K 𝕀A
and the price of a put is
𝔼 e-rT max X-ST,0 1-𝕀A + e-rT K 𝕀A
– The price of an American call option is ess sup 0≤τ≤T 𝔼 e -rτ max S τ -X ,0 and the price of an American put option is ess sup 0≤τ≤T 𝔼 e -rτ max X-Sτ ,0 . Here ess sup 0≤τ≤T denotes the essential supremum over all stopping times τ for the process S which take values in 0,T . If S is a Markov process, then the essential supremum may be replaced with the normal supremum. Note that if the asset S pays no dividends then the price of an American call option is the same as a European call option.

2.4.1 The Black–Scholes Model

The best known model of asset behaviour is the Black–Scholes model. Under the risk-neutral measure, the asset is governed by the SDE
d St St = r-q dt + σ dW t
where r is the continuously compounded risk-free interest rate, q is the continuously compounded dividend yield, σ is the volatility of log-asset returns (i.e., log S t+dt / St ) and W = Wt t≥0 is a standard Brownian motion. Under this model, the price of any option P must solve the Black–Scholes PDE
∂P ∂t + ∂P ∂S r-q S+ 12 ∂2 P ∂S 2 σ 2 S 2 -rP=0
at all times before the option is exercised. This PDE admits a closed form solution for a number of different options.

2.4.2 The Black–Scholes Model with Term Structure

The simplest extension of the Black–Scholes model is to allow r, q and σ to be deterministic functions of time so that
d St St = rt - qt dt + σt dW t .
In this case one can still obtain closed form solutions for some options, e.g., European calls and puts.

2.4.3 The Heston Model

Heston (1993) proposed a stochastic volatility model with the following form
d St St = r-q dt + vt d W t 1 d vt = κ η-vt dt + σ vt d Wt 2
where W 1 and W 2 are two Brownian motions with quadratic covariation given by d W 1,W 2 t = ρ d t . In this model r and q are the continuously compounded risk free interest rate and dividend rate respectively, v= vt t≥0 is the stochastic volatility process, η is the long term mean of volatility, κ is the rate of mean reversion, and σ is the volatility of volatility. The prices of European call and put options in the Heston model are available in closed form up to the evaluation of an integral transform (see Lewis (2000)).

2.4.4 The Heston Model with Term Structure

The Heston model can be extended by allowing the coefficients to become deterministic functions of time:
d St St = rt - qt dt + vt d Wt 1 d vt = κt ηt - vt dt + σt vt d Wt 2
where W 1 and W 2 are two Brownian motions with quadratic covariation given by d W 1,W 2 t = ρt d t . When the coefficients are restricted to being piecewise constant functions of time, the prices of European call and put options can be calculated as described in Elices (2008) and Mikhailov and Nögel (2003).

2.5 Hypergeometric Functions

The confluent hypergeometric function M a,b,x (or F 1 1 a;b;x ) requires a number of techniques to approximate it over the whole parameter a,b space and for all argument x values. For x well within the unit circle x≤ρ<1 (where ρ=0.8 say), and for relatively small parameter values, the function can be well approximated by Taylor expansions, continued fractions or through the solution of the related ordinary differential equation by an explicit, adaptive integrator. For values of x>ρ, one of several transformations can be performed (depending on the value of x) to reformulate the problem in terms of a new argument x′ such that x′≤ρ. If one or more of the parameters is relatively large (e.g., a>30) then recurrence relations can be used in combination to reformulate the problem in terms of parameter values of small size (e.g., a<1).
Approximations to the hypergeometric functions can therefore require all of the above techniques in sequence: a transformation to get an argument well inside the unit circle, a combination of recurrence relations to reduce the parameter sizes, and the approximation of the resulting hypergeometric function by one of a set of approximation techniques. Similar complications arise in the computation of the Gaussian Hypergeometric Function F 1 2 .
All the techniques described above are based on those described in Pearson (2009).

3 Recommendations on Choice and Use of Available Routines

3.1 Vectorized Routine Variants

Many routines in Chapter S which compute functions of a single real argument have variants which operate on vectors of arguments. For example, S18AEF computes the value of the I 0 Bessel function for a single argument, and S18ASF computes the same function for multiple arguments. In general it should be more efficient to use vectorized routines where possible, though to some extent this will depend on the environment from which you call the routines. See Section 4 for a complete list of vectorized routines.

3.2 Elliptic Integrals

IMPORTANT ADVICE: users who encounter elliptic integrals in the course of their work are strongly recommended to look at transforming their analysis directly to one of the Carlson forms, rather than to the traditional canonical Legendre forms. In general, the extra symmetry of the Carlson forms is likely to simplify the analysis, and these symmetric forms are much more stable to calculate. Note, however, that this transformation may eventually lead to the following combination of Carlson forms:
RF 0,1-m,1 - 13 m RD 0,1-m,1
with possibly m→1, which makes RF and RD undefined, although the combination itself remains defined and →1. The routine S21BJF returning the Legendre form E m through this combination makes provision for such a case, and allows m=1.
The routine S21BAF for RC is largely included as an auxiliary to the other routines for elliptic integrals. This integral essentially calculates elementary functions, e.g.,
ln⁡x =x-1 RC 1+x 2 2,x ,  x>0; arcsin⁡x =x RC 1-x 2,1,x≤1; arcsinh⁡x =x RC 1+x 2,1,etc.
In general this method of calculating these elementary functions is not recommended as there are usually much more efficient specific routines available in the Library. However, S21BAF may be used, for example, to compute ln⁡x/x-1 when x is close to 1, without the loss of significant figures that occurs when ln⁡x and x-1 are computed separately.

3.3 Bessel and Airy Functions

For computing the Bessel functions Jν x, Yν x, Iν x and Kν x where x is real and ν=0​ or ​1, special routines are provided, which are much faster than the more general routines that allow a complex argument and arbitrary real ν≥0. Similarly, special routines are provided for computing the Airy functions and their derivatives Ai x, Bi x, Ai′x, Bi′x for a real argument which are much faster than the routines for complex arguments.

3.4 Option Pricing Functions

For the Black–Scholes model, functions are provided to compute prices and derivatives (Greeks) of all the European options listed in Section 2.4. Prices for American call and put options can be obtained by calling S30QCF which uses the Bjerksund and Stensland (2002) approximation to the theoretical value. For the Black–Scholes model with term structure, prices for European call and put options can be obtained by calling D03NDF. The prices of European call and put options in the standard Heston model can be obtained by calling S30NAF, while S30NCF returns the same prices in the Heston model with term structure.

3.5 Hypergeometric Functions

Two routines are provided for the confluent hypergeometric function F 1 1 . Both return values for F 1 1 a;b;x where parameters a and b, and argument x, are all real, but one variant works in a scaled form designed to avoid unnecessary loss of precision. The unscaled routine S22BAF is easier to use and should be chosen in the first instance, changing to the scaled routine S22BBF only if problems are encountered. Similar considerations apply to the Gaussian hypergeometric function routines S22BEF and S22BFF.

4 Functionality Index

Airy function,
Ai, real argument,
scalar S17AGF
vectorized S17AUF
Ai or Ai′, complex argument, optionally scaled S17DGF
Ai′, real argument,
scalar S17AJF
vectorized S17AWF
Bi, real argument,
scalar S17AHF
vectorized S17AVF
Bi or Bi′, complex argument, optionally scaled S17DHF
Bi′, real argument,
scalar S17AKF
vectorized S17AXF
Arccos,
inverse circular cosine S09ABF
Arccosh,
inverse hyperbolic cosine S11ACF
Arcsin,
inverse circular sine S09AAF
Arcsinh,
inverse hyperbolic sine S11ABF
Arctanh,
inverse hyperbolic tangent S11AAF
Bessel function,
I0, real argument,
scalar S18AEF
vectorized S18ASF
I1, real argument,
scalar S18AFF
vectorized S18ATF
Iν, complex argument, optionally scaled S18DEF
J0, real argument,
scalar S17AEF
vectorized S17ASF
J1, real argument,
scalar S17AFF
vectorized S17ATF
Jα ± n(z), complex argument S18GKF
Jν, complex argument, optionally scaled S17DEF
K0, real argument,
scalar S18ACF
vectorized S18AQF
K1, real argument,
scalar S18ADF
vectorized S18ARF
Kν, complex argument, optionally scaled S18DCF
Y0, real argument,
scalar S17ACF
vectorized S17AQF
Y1, real argument,
scalar S17ADF
vectorized S17ARF
Yν, complex argument, optionally scaled S17DCF
beta function,
incomplete S14CCF
Complement of the Cumulative Normal distribution S15ACF
Complement of the Error function,
complex argument, scaled S15DDF
real argument S15ADF
real argument, scaled S15AGF
Cosine,
hyperbolic S10ACF
Cosine Integral S13ACF
Cumulative Normal distribution function S15ABF
Dawson's Integral S15AFF
Digamma function, scaled S14ADF
Elliptic functions, Jacobian, sn, cn, dn,
complex argument S21CBF
real argument S21CAF
Elliptic integral,
general,
of 2nd kind, F(z , k′ , a , b) S21DAF
Legendre form,
complete of 1st kind, K(m) S21BHF
complete of 2nd kind, E (m) S21BJF
of 1st kind, F(ϕ | m) S21BEF
of 2nd kind, E (ϕ ∣ m) S21BFF
of 3rd kind, Π (n ; ϕ ∣ m) S21BGF
symmetrised,
degenerate of 1st kind, RC S21BAF
of 1st kind, RF S21BBF
of 2nd kind, RD S21BCF
of 3rd kind, RJ S21BDF
Erf,
real argument S15AEF
Erfc,
complex argument, scaled S15DDF
real argument S15ADF
erfcx,
real argument S15AGF
Exponential,
complex S01EAF
Exponential Integral S13AAF
Fresnel integral,
C,
scalar S20ADF
vectorized S20ARF
S,
scalar S20ACF
vectorized S20AQF
Gamma function S14AAF
Gamma function,
incomplete S14BAF
Generalized factorial function S14AAF
Hankel function Hν(1) or Hν(2),
complex argument, optionally scaled S17DLF
Hypergeometric functions,
1F1 (a ; b ; x) , confluent, real argument S22BAF
1F1(a ; b ; x), confluent, real argument, scaled form S22BBF
2F1 ( a , b ; c ; x ) , Gauss, real argument S22BEF
2F1 ( a , b ; c ; x ) , Gauss, real argument, scaled form S22BFF
Jacobian theta functions θk(x , q),
real argument S21CCF
Kelvin function,
bei x,
scalar S19ABF
vectorized S19APF
ber x,
scalar S19AAF
vectorized S19ANF
kei x,
scalar S19ADF
vectorized S19ARF
ker x,
scalar S19ACF
vectorized S19AQF
Legendre functions of 1st kind Pnm(x), Pnm(x) S22AAF
Logarithm of 1 + x S01BAF
Logarithm of beta function,
real S14CBF
Logarithm of gamma function,
complex S14AGF
real S14ABF
real, scaled S14AHF
Option Pricing,
American option, Bjerksund and Stensland option price S30QCF
Asian option, geometric continuous average rate price S30SAF
Asian option, geometric continuous average rate price with Greeks S30SBF
binary asset-or-nothing option price S30CCF
binary asset-or-nothing option price with Greeks S30CDF
binary cash-or-nothing option price S30CAF
binary cash-or-nothing option price with Greeks S30CBF
Black–Scholes–Merton option price S30AAF
Black–Scholes–Merton option price with Greeks S30ABF
European option, option prices, using Merton jump-diffusion model S30JAF
European option, option price with Greeks, using Merton jump-diffusion model S30JBF
floating-strike lookback option price S30BAF
floating-strike lookback option price with Greeks S30BBF
Heston's model option price S30NAF
Heston's model option price with Greeks S30NBF
Heston's model with term structure S30NCF
standard barrier option price S30FAF
Polygamma function,
ψ(n)(x), real x S14AEF
ψ(n)(z), complex z S14AFF
psi function S14ACF
psi function derivatives, scaled S14ADF
Scaled modified Bessel function(s),
e − (x)I0(x), real argument,
scalar S18CEF
vectorized S18CSF
e − (x)I1(x), real argument,
scalar S18CFF
vectorized S18CTF
ex K0 (x), real argument,
scalar S18CCF
vectorized S18CQF
ex K1 (x), real argument,
scalar S18CDF
vectorized S18CRF
Sine,
hyperbolic S10ABF
Sine Integral S13ADF
Tangent,
circular S07AAF
hyperbolic S10AAF
Trigamma function, scaled S14ADF
Zeros of Bessel functions Jα(x), Jα′(x), Yα(x), Yα′(x),
scalar S17ALF

5 Auxiliary Routines Associated with Library Routine Arguments

None.

6 Routines Withdrawn or Scheduled for Withdrawal

None.

7 References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Bjerksund P and Stensland G (2002) Closed form valuation of American options Discussion Paper 2002/09 NHH Bergen Norway http://www.nhh.no/
Carlson B C (1965) On computing elliptic integrals and functions J. Math. Phys. 44 36–51
Carlson B C (1977a) Special Functions of Applied Mathematics Academic Press
Carlson B C (1977b) Elliptic integrals of the first kind SIAM J. Math. Anal. 8 231–242
Clenshaw C W (1962) Chebyshev Series for Mathematical Functions Mathematical tables HMSO
Elices A (2008) Models with time-dependent parameters using transform methods: application to Heston’s model arXiv:0708.2020v2
Fox L and Parker I B (1968) Chebyshev Polynomials in Numerical Analysis Oxford University Press
Haug E G (2007) The Complete Guide to Option Pricing Formulas (2nd Edition) McGraw-Hill
Heston S (1993) A closed-form solution for options with stochastic volatility with applications to bond and currency options Review of Financial Studies 6 327–343
Joshi M S (2003) The Concepts and Practice of Mathematical Finance Cambridge University Press
Lewis A L (2000) Option valuation under stochastic volatility Finance Press, USA
Mikhailov S and Nögel U (2003) Heston’s Stochastic Volatility Model Implementation, Calibration and Some Extensions Wilmott Magazine July/August 74–79
Pearson J (2009) Computation of hypergeometric functions MSc Dissertation, Mathematical Institute, University of Oxford
Schonfelder J L (1976) The production of special function routines for a multi-machine library Softw. Pract. Exper. 6(1)
S Chapter Contents
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X01AAF : NAG Library, Mark 26

X01 Chapter Contents
X01 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X01AAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

X01AAF returns the numerical value of π.

2 Specification

FUNCTION X01AAF ( X)
REAL (KIND=nag_wp) X01AAF
REAL (KIND=nag_wp) X

3 Description

None.

4 References

None.

5 Arguments

1:   X – REAL (KIND=nag_wp)Dummy

6 Error Indicators and Warnings

None.

7 Accuracy

The result should be correct to machine precision (see Chapter X02).

8 Parallelism and Performance

X01AAF is not threaded in any implementation.

9 Further Comments

None.

10 Example

None.
X01 Chapter Contents
X01 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X01ABF : NAG Library, Mark 26

X01 Chapter Contents
X01 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X01ABF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

X01ABF returns the numerical value of γ (Euler's constant).

2 Specification

FUNCTION X01ABF ( X)
REAL (KIND=nag_wp) X01ABF
REAL (KIND=nag_wp) X

3 Description

None.

4 References

None.

5 Arguments

1:   X – REAL (KIND=nag_wp)Dummy

6 Error Indicators and Warnings

None.

7 Accuracy

The result should be correct to machine precision (see Chapter X02).

8 Parallelism and Performance

X01ABF is not threaded in any implementation.

9 Further Comments

None.

10 Example

None.
X01 Chapter Contents
X01 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X01 Chapter Contents : NAG Library Manual, Mark 26

X01 Chapter Introduction

NAG Library Chapter Contents

X01 – Mathematical Constants

X01 Chapter Introduction – a description of the Chapter and an overview of the algorithms available

Routine Name | Mark of Introduction | Purpose
X01AAF | 5 | nagf_math_pi Provides the mathematical constant π
X01ABF | 5 | nagf_math_euler Provides the mathematical constant γ (Euler's constant)
X01 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X01 Chapter Introduction : NAG Library, Mark 26

X01 Chapter Contents

NAG Library Chapter Introduction

X01 – Mathematical Constants

▸▿ Contents

1 Scope of the Chapter
2 Background to the Problems
3 Recommendations on Choice and Use of Available Routines
4 Routines Withdrawn or Scheduled for Withdrawal

1 Scope of the Chapter

This chapter is concerned with the provision of mathematical constants required by other routines within the Library.

2 Background to the Problems

Some Library routines require mathematical constants. 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 Available Routines

Although these routines are primarily intended for use by other routines they may be accessed directly by you.
Euler's constant, γ X01ABF
π X01AAF
The argument X of these routines is a dummy argument.

4 Routines Withdrawn or Scheduled for Withdrawal

None.
X01 Chapter Contents
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X02AHF : NAG Library, Mark 26

X02 Chapter Contents
X02 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X02AHF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

X02AHF returns the largest positive argument for which the Fortran intrinsic functions SIN and COS return a result with some meaningful accuracy.

2 Specification

FUNCTION X02AHF ( X)
REAL (KIND=nag_wp) X02AHF
REAL (KIND=nag_wp) X

3 Description

The trigonometric functions sin and cos supplied in some compiler run-time libraries do not return accurate results when their argument is large. Often the related accuracy of a result gets progressively worse as the argument gets larger. X02AHF gives a value beyond which the compiler run-time library returns results with no relative accuracy at all. Note that some run-time libraries do return accurate results for all arguments to sin and cos.

4 References

None.

5 Arguments

1:   X – REAL (KIND=nag_wp)Dummy

6 Error Indicators and Warnings

None.

7 Accuracy

None.

8 Parallelism and Performance

X02AHF is not threaded in any implementation.

9 Further Comments

None.

10 Example

See Section 10 in X02AJF.
X02 Chapter Contents
X02 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X02AJF : NAG Library, Mark 26

X02 Chapter Contents
X02 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X02AJF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

X02AJF returns ε, the value machine precision.

2 Specification

FUNCTION X02AJF ( )
REAL (KIND=nag_wp) X02AJF

3 Description

X02AJF returns machine precision, computed as ε = 12 × b 1-p , where b is the arithmetic base (see X02BHF) and p is the number of significant base-b digits (see X02BJF).
It is important to note that the definition of ε here differs from that in ISO Fortran 95 (1997).

4 References

ISO Fortran 95 (1997) ISO Fortran 95 programming language (ISO/IEC 1539–1:1997)

5 Arguments

None.

6 Error Indicators and Warnings

None.

7 Accuracy

None.

8 Parallelism and Performance

X02AJF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example prints the values of all the functions in Chapter X02. The results will vary from one implementation of the Library to another.

10.1 Program Text

Program Text (x02ajfe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (x02ajfe.r)

X02 Chapter Contents
X02 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X02AKF : NAG Library, Mark 26

X02 Chapter Contents
X02 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X02AKF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

X02AKF returns the smallest positive floating-point number.

2 Specification

FUNCTION X02AKF ( )
REAL (KIND=nag_wp) X02AKF

3 Description

X02AKF returns the smallest positive number in the model of floating-point arithmetic described in the X02 Chapter Introduction. The returned value is equal to b emin-1 , where b is the arithmetic base (see X02BHF) and emin is the minimum exponent (see X02BKF) in the model.

4 References

None.

5 Arguments

None.

6 Error Indicators and Warnings

None.

7 Accuracy

None.

8 Parallelism and Performance

X02AKF is not threaded in any implementation.

9 Further Comments

None.

10 Example

See Section 10 in X02AJF.
X02 Chapter Contents
X02 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X02ALF : NAG Library, Mark 26

X02 Chapter Contents
X02 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X02ALF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

X02ALF returns the largest positive floating-point number.

2 Specification

FUNCTION X02ALF ( )
REAL (KIND=nag_wp) X02ALF

3 Description

X02ALF returns the largest positive number in the model of floating-point arithmetic described in the X02 Chapter Introduction. The returned value is equal to 1- b-p × b emax , where b is the arithmetic base (see X02BHF) and emax is the maximum exponent (see X02BLF) in the model.

4 References

None.

5 Arguments

None.

6 Error Indicators and Warnings

None.

7 Accuracy

None.

8 Parallelism and Performance

X02ALF is not threaded in any implementation.

9 Further Comments

None.

10 Example

See Section 10 in X02AJF.
X02 Chapter Contents
X02 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X02AMF : NAG Library, Mark 26

X02 Chapter Contents
X02 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X02AMF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

X02AMF returns the safe range of floating-point arithmetic.

2 Specification

FUNCTION X02AMF ( )
REAL (KIND=nag_wp) X02AMF

3 Description

X02AMF is defined 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
  • x
  • log x
  • exp log x
  • y log x / log y for any y

4 References

None.

5 Arguments

None.

6 Error Indicators and Warnings

None.

7 Accuracy

None.

8 Parallelism and Performance

X02AMF is not threaded in any implementation.

9 Further Comments

None.

10 Example

See Section 10 in X02AJF.
X02 Chapter Contents
X02 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X02ANF : NAG Library, Mark 26

X02 Chapter Contents
X02 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X02ANF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

X02ANF returns the safe range of complex floating-point arithmetic.

2 Specification

FUNCTION X02ANF ( )
REAL (KIND=nag_wp) X02ANF

3 Description

X02ANF is defined 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:
  • -w
  • 1/w
  • -1/w
  • w
  • log w
  • exp log w
  • y log w / log y for any y
  • 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.

4 References

None.

5 Arguments

None.

6 Error Indicators and Warnings

None.

7 Accuracy

None.

8 Parallelism and Performance

X02ANF is not threaded in any implementation.

9 Further Comments

None.

10 Example

See Section 10 in X02AJF.
X02 Chapter Contents
X02 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X02BBF : NAG Library, Mark 26

X02 Chapter Contents
X02 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X02BBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

X02BBF returns the largest representable positive integer value.

2 Specification

FUNCTION X02BBF ( X)
INTEGER X02BBF
REAL (KIND=nag_wp) X

3 Description

None.

4 References

None.

5 Arguments

1:   X – REAL (KIND=nag_wp)Dummy

6 Error Indicators and Warnings

None.

7 Accuracy

None.

8 Parallelism and Performance

X02BBF is not threaded in any implementation.

9 Further Comments

None.

10 Example

See Section 10 in X02AJF.
X02 Chapter Contents
X02 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X02BEF : NAG Library, Mark 26

X02 Chapter Contents
X02 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X02BEF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

X02BEF returns the maximum number of decimal digits which can be accurately represented over the whole range of floating-point numbers.

2 Specification

FUNCTION X02BEF ( X)
INTEGER X02BEF
REAL (KIND=nag_wp) X

3 Description

None.

4 References

None.

5 Arguments

1:   X – REAL (KIND=nag_wp)Dummy

6 Error Indicators and Warnings

None.

7 Accuracy

None.

8 Parallelism and Performance

X02BEF is not threaded in any implementation.

9 Further Comments

None.

10 Example

See Section 10 in X02AJF.
X02 Chapter Contents
X02 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X02BHF : NAG Library, Mark 26

X02 Chapter Contents
X02 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X02BHF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

X02BHF returns the base argument b of the model of floating-point arithmetic as described in the X02 Chapter Introduction.

2 Specification

FUNCTION X02BHF ( )
INTEGER X02BHF

3 Description

None.

4 References

None.

5 Arguments

None.

6 Error Indicators and Warnings

None.

7 Accuracy

None.

8 Parallelism and Performance

X02BHF is not threaded in any implementation.

9 Further Comments

None.

10 Example

See Section 10 in X02AJF.
X02 Chapter Contents
X02 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X02BJF : NAG Library, Mark 26

X02 Chapter Contents
X02 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X02BJF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

X02BJF returns the precision argument p (i.e., the number of significant base-b digits) of the model of floating-point arithmetic described in the X02 Chapter Introduction.

2 Specification

FUNCTION X02BJF ( )
INTEGER X02BJF

3 Description

None.

4 References

None.

5 Arguments

None.

6 Error Indicators and Warnings

None.

7 Accuracy

None.

8 Parallelism and Performance

X02BJF is not threaded in any implementation.

9 Further Comments

None.

10 Example

See Section 10 in X02AJF.
X02 Chapter Contents
X02 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X02BKF : NAG Library, Mark 26

X02 Chapter Contents
X02 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X02BKF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

X02BKF returns the minimum exponent argument emin of the model of floating-point arithmetic described in the X02 Chapter Introduction.

2 Specification

FUNCTION X02BKF ( )
INTEGER X02BKF

3 Description

None.

4 References

None.

5 Arguments

None.

6 Error Indicators and Warnings

None.

7 Accuracy

None.

8 Parallelism and Performance

X02BKF is not threaded in any implementation.

9 Further Comments

None.

10 Example

See Section 10 in X02AJF.
X02 Chapter Contents
X02 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X02BLF : NAG Library, Mark 26

X02 Chapter Contents
X02 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X02BLF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

X02BLF returns the maximum exponent argument emax of the model of floating-point arithmetic described in the X02 Chapter Introduction.

2 Specification

FUNCTION X02BLF ( )
INTEGER X02BLF

3 Description

None.

4 References

None.

5 Arguments

None.

6 Error Indicators and Warnings

None.

7 Accuracy

None.

8 Parallelism and Performance

X02BLF is not threaded in any implementation.

9 Further Comments

None.

10 Example

See Section 10 in X02AJF.
X02 Chapter Contents
X02 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X02 Chapter Contents : NAG Library Manual, Mark 26

X02 Chapter Introduction

NAG Library Chapter Contents

X02 – Machine Constants

X02 Chapter Introduction – a description of the Chapter and an overview of the algorithms available

Routine Name | Mark of Introduction | Purpose
X02AHF | 9 | nagf_machine_sinarg_max The largest permissible argument for sin and cos
X02AJF Example Text | 12 | nagf_machine_precision The machine precision
X02AKF | 12 | nagf_machine_real_smallest The smallest positive model number
X02ALF | 12 | nagf_machine_real_largest The largest positive model number
X02AMF | 12 | nagf_machine_real_safe The safe range parameter
X02ANF | 15 | nagf_machine_complex_safe The safe range parameter for complex floating-point arithmetic
X02BBF | 5 | nagf_machine_integer_max The largest representable integer
X02BEF | 5 | nagf_machine_decimal_digits The maximum number of decimal digits that can be represented
X02BHF | 12 | nagf_machine_model_base The floating-point model parameter, b
X02BJF | 12 | nagf_machine_model_digits The floating-point model parameter, p
X02BKF | 12 | nagf_machine_model_minexp The floating-point model parameter emin
X02BLF | 12 | nagf_machine_model_maxexp The floating-point model parameter emax
X02 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X02 Chapter Introduction : NAG Library, Mark 26

X02 Chapter Contents

NAG Library Chapter Introduction

X02 – Machine Constants

▸▿ Contents

1 Scope of the Chapter
▸▿ 2 Background to the Problems
▸▿ 2.1 Floating-point Arithmetic
2.1.1 A model of floating-point arithmetic
2.1.2 Derived parameters of floating-point arithmetic
2.2 Other Aspects of the Computing Environment
3 Recommendations on Choice and Use of Available Routines
4 Routines Withdrawn or Scheduled for Withdrawal
5 References

1 Scope of the Chapter

This chapter is concerned with parameters which characterise certain aspects of the computing environment in which the NAG Library is implemented. They relate primarily to floating-point arithmetic, but also to integer arithmetic, the elementary functions and exception handling. 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.

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 (1981), but differs in some respects. The essential features are summarised here.
The model is characterised by four integer parameters. The four integer parameters are:
b: | the base
p: | the precision (i.e., the number of significant base-b digits)
emin: | the minimum exponent
emax: | the maximum exponent
These parameters define a set of numerical values of the form:
f×be
where the exponent e must lie in the range [emin,emax], and the fraction f (also called the mantissa or significand) lies in the range 1 / b ,1 , and may be written
f=0. f 1f 2⋯fp
Thus f is a p-digit fraction to the base b; the fi are the base-b digits of the fraction: they are integers in the range 0 to b-1, and the leading digit f 1 must not be zero.
The set of values so defined (together with zero) are called model numbers. For example, if b=10, p=5, emin=-99 and emax=+99, then a typical model number is 0.12345×1067.
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 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.
For division and square root, this latter rule is relaxed: the computed result may also be one of the next adjacent model numbers on either side of the permitted values just stated.
On many machines, the full set of representable floating-point numbers conforms to the rules of the model with appropriate values of b, p, emin and emax. For machines supporting IEEE binary double precision arithmetic:
b = 2 p = 53 emin = -1021 emax = 1024.
(Note: the model used here differs from that described in Brown (1981) in the following respect: square-root is treated, like division, as a weakly supported operator.)

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:
the machine precision ε: | =12 ×b 1-p
the smallest positive model number: | =b emin-1
the largest positive model number: | =1-b-p×b emax
It is important to note that the machine precision defined here differs from that defined by ISO Fortran 95 (1997).
Two additional derived values are used in the NAG 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
  • 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
  • w
  • log w
  • exp log w
  • y log w / log y for any y
  • 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.

3 Recommendations on Choice and Use of Available Routines

Derived parameters of model of floating-point arithmetic,
largest positive model number X02ALF
machine precision X02AJF
safe range X02AMF
safe range of complex floating-point arithmetic X02ANF
smallest positive model number X02AKF
Largest permissible argument for SIN and COS X02AHF
Largest representable integer X02BBF
Maximum number of decimal digits that can be represented X02BEF
Parameters of model of floating-point arithmetic,
b X02BHF
emax X02BLF
emin X02BKF
p X02BJF

4 Routines Withdrawn or Scheduled for Withdrawal

The following lists all those routines that have been withdrawn since Mark 19 of the Library or are scheduled for withdrawal at one of the next two marks.
Withdrawn Routine | Mark of Withdrawal | Replacement Routine(s)
X02DAF | 24 | No longer required
X02DJF | 24 | No longer required

5 References

Brown W S (1981) A simple but realistic model of floating-point computation ACM Trans. Math. Software 7 445–480
ISO Fortran 95 (1997) ISO Fortran 95 programming language (ISO/IEC 1539–1:1997)
X02 Chapter Contents
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X03AAF : NAG Library, Mark 26

X03 Chapter Contents
X03 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X03AAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

X03AAF calculates the value of a scalar product using basic precision or additional precision and adds it to a basic precision or additional precision initial value.

2 Specification

SUBROUTINE X03AAF ( A, ISIZEA, B, ISIZEB, N, ISTEPA, ISTEPB, C1, C2, D1, D2, SW, IFAIL)
INTEGER | ISIZEA, ISIZEB, N, ISTEPA, ISTEPB, IFAIL
REAL (KIND=nag_wp) | A(ISIZEA), B(ISIZEB), C1, C2, D1, D2
LOGICAL | SW

3 Description

X03AAF calculates the scalar product of two real vectors and adds it to an initial value c to give a correctly rounded result d:
d=c+∑i=1 n aibi.
If n<1, d=c.
The vector elements ai and bi are stored in selected elements of the one-dimensional array arguments A and B, which in the subroutine from which X03AAF is called may be identified with parts of possibly multidimensional arrays according to the standard Fortran rules. For example, the vectors may be parts of a row or column of a matrix. See Section 5 for details, and Section 10 for an example.
Both the initial value c and the result d are defined by a pair of real variables, so that they may take either basic precision or additional precision values.
(a) | If SW=.TRUE., the products are accumulated in additional precision, and on exit the result is available either in basic precision, correctly rounded, or in additional precision.
(b) | If SW=.FALSE., the products are accumulated in basic precision, and the result is returned in basic precision.
This routine is designed primarily for use as an auxiliary routine by other routines in the NAG Library, especially those in the chapters on Linear Algebra.

4 References

None.

5 Arguments

1:   A ISIZEA – REAL (KIND=nag_wp) arrayInput
On entry: the elements of the first vector.
The ith vector element is stored in the array element A i-1×ISTEPA+1 . In your subroutine from which X03AAF is called, A can be part of a multidimensional array and the actual argument must be the array element containing the first vector element.
2:   ISIZEA – INTEGERInput
On entry: the dimension of the array A as declared in the (sub)program from which X03AAF is called.
The upper bound for ISIZEA is found by multiplying together the dimensions of A as declared in your subroutine from which X03AAF is called, subtracting the starting position and adding 1.
Constraint: ISIZEA≥N-1×ISTEPA+1.
3:   B ISIZEB – REAL (KIND=nag_wp) arrayInput
On entry: the elements of the second vector.
The ith vector element is stored in the array element B i-1×ISTEPB+1 . In your subroutine from which X03AAF is called, B can be part of a multidimensional array and the actual argument must be the array element containing the first vector element.
4:   ISIZEB – INTEGERInput
On entry: the dimension of the array B as declared in the (sub)program from which X03AAF is called.
The upper bound for ISIZEB is found by multiplying together the dimensions of B as declared in your subroutine from which X03AAF is called, subtracting the starting position and adding 1.
Constraint: ISIZEB≥N-1×ISTEPB+1.
5:   N – INTEGERInput
On entry: n, the number of elements in the scalar product.
6:   ISTEPA – INTEGERInput
On entry: the step length between elements of the first vector in array A.
Constraint: ISTEPA>0.
7:   ISTEPB – INTEGERInput
On entry: the step length between elements of the second vector in array B.
Constraint: ISTEPB>0.
8:   C1 – REAL (KIND=nag_wp)Input
9:   C2 – REAL (KIND=nag_wp)Input
On entry: C1 and C2 must specify the initial value c: c=C1+C2. Normally, if c is in additional precision, C1 specifies the most significant part and C2 the least significant part; if c is in basic precision, then C1 specifies c and C2 must have the value 0.0. Both C1 and C2 must be defined on entry.
10:   D1 – REAL (KIND=nag_wp)Output
11:   D2 – REAL (KIND=nag_wp)Output
On exit: the result d.
If the calculation is in additional precision (SW=.TRUE.),
  • D1=d rounded to basic precision;
  • D2=d-D1,
thus D1 holds the correctly rounded basic precision result and the sum D1+D2 gives the result in additional precision. D2 may have the opposite sign to D1.
If the calculation is in basic precision (SW=.FALSE.),
  • D1=d;
  • D2=0.0.
12:   SW – LOGICALInput
On entry: the precision to be used in the calculation.
SW=.TRUE.
additional precision.
SW=.FALSE.
basic precision.
13:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | ISTEPA≤0,
or | ISTEPB≤0.
IFAIL=2
On entry, | ISIZEA>N-1×ISTEPA+1,
or | ISIZEB>N-1×ISTEPB+1.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

If the calculation is an additional precision, the rounded basic precision result D1 is correct to full implementation accuracy, provided that exceptionally severe cancellation does not occur in the summation. If the calculation is in basic precision, such accuracy cannot be guaranteed.

8 Parallelism and Performance

X03AAF is not threaded in any implementation.

9 Further Comments

The time taken by X03AAF is approximately proportional to n and also depends on whether basic precision or additional precision is used.
On exit the variables D1 and D2 may be used directly to supply a basic precision or additional precision initial value for a subsequent call of X03AAF.

10 Example

This example calculates the scalar product of the second column of the matrix A and the vector B, and add it to an initial value 1.0 where
A= -2 -3 7 2 -5 3 -9 1 0 ,  B= 8 -4 -2 .

10.1 Program Text

Program Text (x03aafe.f90)

10.2 Program Data

Program Data (x03aafe.d)

10.3 Program Results

Program Results (x03aafe.r)

X03 Chapter Contents
X03 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X03ABF : NAG Library, Mark 26

X03 Chapter Contents
X03 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X03ABF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

X03ABF calculates the value of a complex scalar product using basic precision or additional precision and adds it to a complex initial value.

2 Specification

SUBROUTINE X03ABF ( A, ISIZEA, B, ISIZEB, N, ISTEPA, ISTEPB, CX, DX, SW, IFAIL)
INTEGER | ISIZEA, ISIZEB, N, ISTEPA, ISTEPB, IFAIL
COMPLEX (KIND=nag_wp) | A(ISIZEA), B(ISIZEB), CX, DX
LOGICAL | SW

3 Description

X03ABF calculates the scalar product of two complex vectors and adds it to an initial value c to give a correctly rounded result d:
d=c+∑i=1 n aibi.
If n<1, d=c.
The vector elements ai and bi are stored in selected elements of the one-dimensional array arguments A and B, which in the subroutine from which X03ABF is called may be identified with parts of possibly multidimensional arrays according to the standard Fortran rules. For example, the vectors may be parts of a row or column of a matrix. See Section 5 for details, and Section 10 for an example.
The products are accumulated in basic precision or additional precision depending on the argument SW.
This routine has been designed primarily for use as an auxiliary routine by other routines in the NAG Library, especially those in the chapters on Linear Algebra.

4 References

None.

5 Arguments

1:   A ISIZEA – COMPLEX (KIND=nag_wp) arrayInput
On entry: the elements of the first vector.
The ith vector element is stored in the array element A i-1×ISTEPA+1 . In your subroutine from which X03ABF is called, A can be part of a multidimensional array and the actual argument must be the array element containing the first vector element.
2:   ISIZEA – INTEGERInput
On entry: the dimension of the array A as declared in the (sub)program from which X03ABF is called.
The upper bound for ISIZEA is found by multiplying together the dimensions of A as declared in your subroutine from which X03ABF is called, subtracting the starting position and adding 1.
Constraint: ISIZEA≥N-1×ISTEPA+1.
3:   B ISIZEB – COMPLEX (KIND=nag_wp) arrayInput
On entry: the elements of the second vector.
The ith vector element is stored in the array element B i-1×ISTEPB+1 . In your subroutine from which X03ABF is called, B can be part of a multidimensional array and the actual argument must be the array element containing the first vector element.
4:   ISIZEB – INTEGERInput
On entry: the dimension of the array B as declared in the (sub)program from which X03ABF is called.
The upper bound for ISIZEB is found by multiplying together the dimensions of B as declared in your subroutine from which X03ABF is called, subtracting the starting position and adding 1.
Constraint: ISIZEB≥N-1×ISTEPB+1.
5:   N – INTEGERInput
On entry: n, the number of elements in the scalar product.
6:   ISTEPA – INTEGERInput
On entry: the step length between elements of the first vector in array A.
Constraint: ISTEPA>0.
7:   ISTEPB – INTEGERInput
On entry: the step length between elements of the second vector in array B.
Constraint: ISTEPB>0.
8:   CX – COMPLEX (KIND=nag_wp)Input
On entry: the initial value c.
9:   DX – COMPLEX (KIND=nag_wp)Output
On exit: the result d.
10:   SW – LOGICALInput
On entry: the precision to be used in the calculation.
SW=.TRUE.
additional precision.
SW=.FALSE.
basic precision.
11:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, | ISTEPA≤0,
or | ISTEPB≤0.
IFAIL=2
On entry, | ISIZEA<N-1×ISTEPA+1,
or | ISIZEB<N-1×ISTEPB+1.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

If the calculation is in additional precision, the result is correct to full implementation accuracy provided that exceptionally severe cancellation does not occur in the summation. If the calculation is in basic precision, such accuracy cannot be guaranteed.

8 Parallelism and Performance

X03ABF is not threaded in any implementation.

9 Further Comments

The time taken by X03ABF is approximately proportional to n and also depends on whether basic precision or additional precision is used.

10 Example

This example calculates the scalar product of the second column of the matrix A and the vector B, and add it to an initial value of 1+i, where
A= -1 -i 1 -2+3 i i 2 i -0 -1-i 1-2 i ,  B= i 1-i -i .

10.1 Program Text

Program Text (x03abfe.f90)

10.2 Program Data

Program Data (x03abfe.d)

10.3 Program Results

Program Results (x03abfe.r)

X03 Chapter Contents
X03 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X03 Chapter Contents : NAG Library Manual, Mark 26

X03 Chapter Introduction

NAG Library Chapter Contents

X03 – Inner Products

X03 Chapter Introduction – a description of the Chapter and an overview of the algorithms available

Routine Name | Mark of Introduction | Purpose
X03AAF Example Text Example Data | 5 | nagf_dot_real_prec Real inner product added to initial value, basic/additional precision
X03ABF Example Text Example Data | 5 | nagf_dot_complex_prec Complex inner product added to initial value, basic/additional precision
X03 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X03 Chapter Introduction : NAG Library, Mark 26

X03 Chapter Contents

NAG Library Chapter Introduction

X03 – Inner Products

▸▿ Contents

1 Scope of the Chapter
2 Background to the Problems
3 Recommendations on Choice and Use of Available Routines
4 Routines Withdrawn or Scheduled for Withdrawal

1 Scope of the Chapter

This chapter is concerned with the calculation of innerproducts required by other routines within the Library.

2 Background to the Problems

Some Library routines require to calculate the innerproduct
c+∑ixiyi,
preferably in additional precision, but, if this is unavailable or prohibitively expensive, then in basic precision. These routines call Chapter X03 so that machine dependencies of this type can be isolated to this chapter.

3 Recommendations on Choice and Use of Available Routines

Although these routines are primarily intended for use by other Library routines they may be accessed directly by you:
X03AAF calculates the innerproduct for real values c, xi and yi,
X03ABF calculates the innerproduct for complex values c, xi and yi,

4 Routines Withdrawn or Scheduled for Withdrawal

None.
X03 Chapter Contents
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X04AAF : NAG Library, Mark 26

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X04AAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

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

X04AAF 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 Arguments

1:   IFLAG – INTEGERInput
On entry: the action to be taken (see NERR).
Constraint: IFLAG=0 or 1.
2:   NERR – INTEGERInput/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. It is important to note that if you supply an illegal value for NERR (such as a unit number associated with a file opened for reading instead of writing) then X04AAF cannot detect that fact, but any output sent to the unit by later calls of NAG routines may have undesirable consequences, such as program crashes.

6 Error Indicators and Warnings

None.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X04AAF is not thread safe and should not be called from a multithreaded user program. Please see Section 3.12.1 in How to Use the NAG Library and its Documentation for more information on thread safety.
X04AAF is not threaded in any implementation.

9 Further Comments

The time taken by X04AAF is negligible.

10 Example

In this example X04AAF is called by your 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 Library routine with an IFAIL argument (see Section 3.4.2 in How to Use the NAG Library and its Documentation) would take the place of DUMMY.

10.1 Program Text

Program Text (x04aafe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (x04aafe.r)

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X04ABF : NAG Library, Mark 26

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X04ABF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

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

X04ABF 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 Users' 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 you to specify longer records.
Note that if the unit number is set <0, no messages will be output.

4 References

None.

5 Arguments

1:   IFLAG – INTEGERInput
On entry: the action to be taken (see NADV).
Constraint: IFLAG=0 or 1.
2:   NADV – INTEGERInput/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. It is important to note that if you supply an illegal value for NADV (such as a unit number associated with a file opened for reading instead of writing) then X04ABF cannot detect that fact, but any output sent to the unit by later calls of NAG routines may have undesirable consequences, such as program crashes.

6 Error Indicators and Warnings

None.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X04ABF is not thread safe and should not be called from a multithreaded user program. Please see Section 3.12.1 in How to Use the NAG Library and its Documentation for more information on thread safety.
X04ABF is not threaded in any implementation.

9 Further Comments

The time taken by X04ABF is negligible.

10 Example

In this example X04ABF is called by your 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 Library routine with an IFAIL argument (see Section 3.4.2 in How to Use the NAG Library and its Documentation) would take the place of DUMMY.

10.1 Program Text

Program Text (x04abfe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (x04abfe.r)

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X04ACF : NAG Library, Mark 26

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X04ACF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

X04ACF opens a Fortran unit number for reading, writing or appending, and associates the unit with a named file.

2 Specification

SUBROUTINE X04ACF ( IOUNIT, FILE, MODE, IFAIL)
INTEGER | IOUNIT, MODE, IFAIL
CHARACTER(*) | FILE

3 Description

X04ACF is especially useful if the calling language is not Fortran. It opens a Fortran unit number for reading, writing or appending, and associates the unit with a filename specified by the argument FILE.

4 References

None.

5 Arguments

1:   IOUNIT – INTEGERInput
On entry: the Fortran unit number which identifies the file to be read from, written to or appended to. Note that this may be system dependent. Values in the range 7 to 1000 should however be safe on most systems.
2:   FILE – CHARACTER(*)Input
On entry: the name of the file to be opened.
Constraint: must contain a valid filename for the computer system being used.
3:   MODE – INTEGERInput
On entry: specifies whether the file is to be opened for reading, writing or appending.
MODE=0
The file is to be opened for reading.
MODE=1
The file is to be opened for writing.
MODE=2
The file is to be opened for appending.
Constraint: 0≤MODE≤2.
4:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, MODE is invalid.
IFAIL=2
Failure to open the file for reading.
IFAIL=3
Failure to open the file for writing.
IFAIL=4
Failure to open the file for appending.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X04ACF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example illustrates how to open a file for writing.

10.1 Program Text

Program Text (x04acfe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (x04acfe.r)

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X04ADF : NAG Library, Mark 26

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X04ADF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

X04ADF closes a file associated with a given Fortran unit number.

2 Specification

SUBROUTINE X04ADF ( IOUNIT, IFAIL)
INTEGER IOUNIT, IFAIL

3 Description

X04ADF is especially useful if the calling language is not Fortran. It closes a file associated with a given Fortran unit number.

4 References

None.

5 Arguments

1:   IOUNIT – INTEGERInput
On entry: the Fortran unit number which identifies the file to be closed.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
Failure to close the file.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X04ADF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example program simply illustrates how to close a file once it has been opened for writing followed by how to close a file once it has been opened for reading.

10.1 Program Text

Program Text (x04adfe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (x04adfe.r)

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X04BAF : NAG Library, Mark 26

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X04BAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

X04BAF writes a single formatted record to an external file.

2 Specification

SUBROUTINE X04BAF ( NOUT, REC)
INTEGER | NOUT
CHARACTER(*) | REC

3 Description

X04BAF is used by NAG Library routines to write formatted records to an external file. All formatted output to an external file from NAG Library routines is performed by calls to X04BAF.

4 References

None.

5 Arguments

1:   NOUT – INTEGERInput
On entry: the Fortran unit number which identifies the file to be written to. If NOUT<0 (not a valid Fortran unit number), then no output occurs. Within the NAG Library NOUT is always determined by a call to X04AAF or X04ABF.
2:   REC – CHARACTER(*)Input
On entry: a character-string. This is written to the external file as a single record. Trailing blanks are not output, except that if REC is entirely blank, a single blank character is output. If the record is printed, the first character is treated as a carriage-control character.

6 Error Indicators and Warnings

None.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X04BAF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example program simply illustrates how a formatted record is output from the NAG Library, by first writing it to the character-string REC, used as an internal file, and then passing the character-string to X04BAF.

10.1 Program Text

Program Text (x04bafe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (x04bafe.r)

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X04BBF : NAG Library, Mark 26

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X04BBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

X04BBF reads a single formatted record from an external file.

2 Specification

SUBROUTINE X04BBF ( NIN, RECIN, IFAIL)
INTEGER | NIN, IFAIL
CHARACTER(*) | RECIN

3 Description

X04BBF is used by NAG Library routines to read formatted records from an external file. All formatted input from an external file by NAG Library routines is performed by calls to X04BBF.

4 References

None.

5 Arguments

1:   NIN – INTEGERInput
On entry: the Fortran unit number which identifies the file to be read from. If NIN<0 (not a valid Fortran unit number), then no input occurs.
2:   RECIN – CHARACTER(*)Output
On exit: the first LEN(RECIN) characters of the record read from unit NIN, padded with trailing blanks if the record was shorter than LEN(RECIN).
3:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
An end-of-file was detected by the READ statement.
System-dependent errors may also occur if the unit specified by NIN is not connected to an external file, or if a read error occurs.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X04BBF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example program simply illustrates how a formatted record is read from the NAG Library, by first reading it into the character-string RECIN, used as an internal file, by X04BBF and then reading the internal file.

10.1 Program Text

Program Text (x04bbfe.f90)

10.2 Program Data

Program Data (x04bbfe.d)

10.3 Program Results

Program Results (x04bbfe.r)

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X04CAF : NAG Library, Mark 26

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X04CAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

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, IFAIL)
INTEGER | M, N, LDA, IFAIL
REAL (KIND=nag_wp) | A(LDA,*)
CHARACTER(*) | TITLE
CHARACTER(1) | MATRIX, DIAG

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 an F 8.4, an F 11.4 or a 1 PE 13.4 format. The F 8.4 code is chosen if the sizes of all the matrix elements to be printed lie between 0.001 and 1.0. The F 11.4 code is chosen if the sizes of all the matrix elements to be printed lie between 0.001 and 9999.9999. Otherwise the 1 PE 13.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 Arguments

1:   MATRIX – CHARACTER(1)Input
On entry: indicates the part of the matrix to be printed.
MATRIX='G'
The whole of the rectangular matrix.
MATRIX='L'
The lower triangle of the matrix, or the lower trapezium if the matrix has more rows than columns.
MATRIX='U'
The upper triangle of the matrix, or the upper trapezium if the matrix has more columns than rows.
Constraint: MATRIX='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.
DIAG='B'
The diagonal elements of the matrix are not referenced and not printed.
DIAG='U'
The diagonal elements of the matrix are not referenced, but are assumed all to be unity, and are printed as such.
DIAG='N'
The diagonal elements of the matrix are referenced and printed.
If MATRIX='G', then DIAG need not be set.
Constraint: if MATRIX≠'G', DIAG='B', 'U' or 'N'.
3:   M – INTEGERInput
4:   N – INTEGERInput
On entry: the number of rows and columns of the matrix, respectively, to be printed.
If either M or N is less than 1, X04CAF will exit immediately after printing TITLE; no row or column labels are printed.
5:   A LDA* – REAL (KIND=nag_wp) arrayInput
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 arguments MATRIX and DIAG, need be set.
6:   LDA – INTEGERInput
On entry: the first dimension of the array A as declared in the (sub)program from which X04CAF is called.
Constraint: LDA≥max 1,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 – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
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.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X04CAF is not threaded in any implementation.

9 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'
FORM = ' '

10 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.

10.1 Program Text

Program Text (x04cafe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (x04cafe.r)

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X04CBF : NAG Library, Mark 26

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X04CBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

X04CBF prints a real matrix stored in a two-dimensional array.

2 Specification

SUBROUTINE X04CBF ( MATRIX, DIAG, M, N, A, LDA, FORM, TITLE, LABROW, RLABS, LABCOL, CLABS, NCOLS, INDENT, IFAIL)
INTEGER | M, N, LDA, NCOLS, INDENT, IFAIL
REAL (KIND=nag_wp) | A(LDA,*)
CHARACTER(*) | FORM, TITLE, RLABS(*), CLABS(*)
CHARACTER(1) | MATRIX, DIAG, LABROW, LABCOL

3 Description

X04CBF prints a real matrix, or part of it, using a format specifier supplied by you. The matrix is output to the unit defined by X04ABF.

4 References

None.

5 Arguments

1:   MATRIX – CHARACTER(1)Input
On entry: indicates the part of the matrix to be printed.
MATRIX='G'
The whole of the rectangular matrix.
MATRIX='L'
The lower triangle of the matrix, or the lower trapezium if the matrix has more rows than columns.
MATRIX='U'
The upper triangle of the matrix, or the upper trapezium if the matrix has more columns than rows.
Constraint: MATRIX='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.
DIAG='B'
The diagonal elements of the matrix are not referenced and not printed.
DIAG='U'
The diagonal elements of the matrix are not referenced, but are assumed all to be unity, and are printed as such.
DIAG='N'
The diagonal elements of the matrix are referenced and printed.
If MATRIX='G', then DIAG need not be set.
Constraint: if MATRIX≠'G', DIAG='B', 'U' or 'N'.
3:   M – INTEGERInput
4:   N – INTEGERInput
On entry: the number of rows and columns of the matrix, respectively, to be printed.
If either M or N is less than 1, X04CBF will exit immediately after printing TITLE; no row or column labels are printed.
5:   A LDA* – REAL (KIND=nag_wp) arrayInput
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 arguments MATRIX and DIAG, need be set.
6:   LDA – INTEGERInput
On entry: the first dimension of the array A as declared in the (sub)program from which X04CBF is called.
Constraint: LDA≥max 1,M.
7:   FORM – CHARACTER(*)Input
On entry: describes the Fortran format code for printing the elements of the matrix A. The format code may be any allowed on the system, whether it is standard Fortran or not. It may or may not be enclosed in brackets.
In addition, there are the following special codes which force X04CBF to choose its own format code:
FORM=' '
X04CBF will choose a format code such that numbers will be printed with an F8.4, an 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.
FORM='*'
X04CBF will choose a format code such that numbers will be printed to as many significant digits as are necessary to distinguish between neighbouring machine numbers. Thus any two numbers that are stored with different internal representations should look different on output. Whether they do in fact look different will depend on the run-time library of the Fortran compiler in use.
By preceding the desired format code by the string ‘MATLAB’, X04CBF will print the matrix such that it can be input into MATLAB, and TITLE will be used as the name of the matrix.
Examples of valid values for FORM are 'F11.4', '1PE13.5', 'G14.5', 'MATLABF11.4', 'MATLAB*'.
Constraint: the character length of the format specifier in FORM must be ≤80.
8:   TITLE – CHARACTER(*)Input
On entry: a title to be printed above the matrix, or name of the matrix.
If TITLE=' ', no title (and no blank line) will be printed.
If TITLE contains more than NCOLS characters, the contents of TITLE will be wrapped onto more than one line, with the break after NCOLS characters.
Any trailing blank characters in TITLE are ignored.
If printing in MATLAB mode, TITLE will be used as the name of the matrix.
9:   LABROW – CHARACTER(1)Input
On entry: indicates the type of labelling to be applied to the rows of the matrix, except in MATLAB mode where LABROW is ignored.
LABROW='N'
Prints no row labels.
LABROW='I'
Prints integer row labels.
LABROW='C'
Prints character labels, which must be supplied in array RLABS.
Constraint: LABROW='N', 'I' or 'C'.
10:   RLABS* – CHARACTER(*) arrayInput
Note: the dimension of the array RLABS must be at least M if LABROW='C', and at least 1 otherwise.
On entry: if LABROW='C', RLABS must contain labels for the rows of the matrix, except in MATLAB mode where RLABS is ignored.
Labels are right-justified when output, in a field which is as wide as necessary to hold the longest row label. Note that this field width is subtracted from the number of usable columns, NCOLS.
11:   LABCOL – CHARACTER(1)Input
On entry: indicates the type of labelling to be applied to the columns of the matrix, except in MATLAB mode where LABCOL is ignored.
LABCOL='N'
Prints no column labels.
LABCOL='I'
Prints integer column labels.
LABCOL='C'
Prints character labels, which must be supplied in array CLABS.
Constraint: LABCOL='N', 'I' or 'C'.
12:   CLABS* – CHARACTER(*) arrayInput
Note: the dimension of the array CLABS must be at least N if LABCOL='C', and at least 1 otherwise.
On entry: if LABCOL='C', CLABS must contain labels for the columns of the matrix, except in MATLAB mode where CLABS is ignored.
Labels are right-justified when output. Any label that is too long for the column width, which is determined by FORM, is truncated.
13:   NCOLS – INTEGERInput
On entry: the maximum output record length. If the number of columns of the matrix is too large to be accommodated in NCOLS characters, the matrix will be printed in parts, containing the largest possible number of matrix columns, and each part separated by a blank line.
NCOLS must be large enough to hold at least one column of the matrix using the format specifier in FORM. If a value less than 0 or greater than 132 is supplied for NCOLS, then the value 80 is used instead.
14:   INDENT – INTEGERInput
On entry: the number of columns by which the matrix (and any title and labels) should be indented. The effective value of NCOLS is reduced by INDENT columns. If a value less than 0 or greater than NCOLS is supplied for INDENT, the value 0 is used instead.
15:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
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.
IFAIL=4
On entry, the format specifier in FORM is more than 80 characters long.
IFAIL=5
The format specifier in FORM cannot be used to output a number. The specifier probably has too wide a field width or contains an illegal edit descriptor.
IFAIL=6
On entry, either LABROW or LABCOL≠'N', 'I' or 'C'.
IFAIL=7
The quantity NCOLS-INDENT-labwid (where labwid is the width needed for the row labels), is not large enough to hold at least one column of the matrix.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X04CBF is not threaded in any implementation.

9 Further Comments

X04CBF may be used to print a vector, either as a row or as a column. The following code fragment illustrates possible calls.
      REAL (KIND=nag_wp) A(4)
      CHARACTER*1        RLABS(1), CLABS(1)
!     Print vector A as a column vector.
      LDA = 4
      IFAIL = 0
      CALL X04CBF('G','X',1,4,A,LDA,' ',' ','I',RLABS, &
                  'N',CLABS,80,0,IFAIL)
!     Print vector A as a row vector.
      LDA = 1
            IFAIL = 0
      CALL X04CBF('G','X',4,1,A,LDA,' ',' ','N',RLABS, &
                  'I',CLABS,80,0,IFAIL)

10 Example

This example calls X04CBF twice, to print matrices of different orders and bandwidths; various options for labelling and formatting are illustrated.

10.1 Program Text

Program Text (x04cbfe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (x04cbfe.r)

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X04CCF : NAG Library, Mark 26

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X04CCF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

X04CCF is an easy-to-use routine to print a real triangular matrix stored in a packed one-dimensional array.

2 Specification

SUBROUTINE X04CCF ( UPLO, DIAG, N, A, TITLE, IFAIL)
INTEGER | N, IFAIL
REAL (KIND=nag_wp) | A(*)
CHARACTER(*) | TITLE
CHARACTER(1) | UPLO, DIAG

3 Description

X04CCF prints a real triangular matrix stored in packed form. It is an easy-to-use driver for X04CDF. The routine uses default values for the format in which numbers are printed, for labelling the rows and columns, and for output record length. The matrix must be packed by column.
X04CCF will choose a format code such that numbers will be printed with an F 8.4, an F 11.4 or a 1 PE 13.4 format . The F 8.4 code is chosen if the sizes of all the matrix elements to be printed lie between 0.001 and 1.0. The F 11.4 code is chosen if the sizes of all the matrix elements to be printed lie between 0.001 and 9999.9999. Otherwise the 1 PE 13.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 Arguments

1:   UPLO – CHARACTER(1)Input
On entry: indicates the type of the matrix to be printed
UPLO='L'
The matrix is lower triangular. In this case, the packed array A holds the matrix elements in the following order: 1,1,2,1,…,N,1,2,2,3,2,…,N,2, etc.
UPLO='U'
The matrix is upper triangular. In this case, the packed array A holds the matrix elements in the following order: 1,1,1,2,2,2,1,3,2,3,3,3,1,4, etc.
Constraint: UPLO='L' or 'U'.
2:   DIAG – CHARACTER(1)Input
On entry: indicates whether the diagonal elements of the matrix are to be printed.
DIAG='B'
The diagonal elements of the matrix are not referenced and not printed.
DIAG='U'
The diagonal elements of the matrix are not referenced, but are assumed all to be unity, and are printed as such.
DIAG='N'
The diagonal elements of the matrix are referenced and printed.
Constraint: DIAG='B', 'U' or 'N'.
3:   N – INTEGERInput
On entry: the order of the matrix to be printed.
If N is less than 1, X04CCF will exit immediately after printing TITLE; no row or column labels are printed.
4:   A* – REAL (KIND=nag_wp) arrayInput
Note: the dimension of the array A must be at least max 1,N×N+1/2.
On entry: the matrix to be printed. Note that A must have space for the diagonal elements of the matrix, even if these are not stored.
More precisely,
  • if UPLO='U', the upper triangle of A must be stored with element A ij in A i+j j-1/2 for i≤j;
  • if UPLO='L', the lower triangle of A must be stored with element A ij in A i+2 n-jj-1/2 for i≥j.
If DIAG='U', the diagonal elements of A are assumed to be 1, and are not referenced; the same storage scheme is used whether DIAG='N' or ‘U’.
5:   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.
6:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, UPLO≠'L' or 'U'.
IFAIL=2
On entry, DIAG≠'N', 'U' or 'B'.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X04CCF is not threaded in any implementation.

9 Further Comments

A call to X04CCF is equivalent to a call to X04CDF with the following argument values:

NCOLS = 80
INDENT = 0
LABROW = 'I'
LABCOL = 'I'
FORM = ' '

10 Example

The example program calls X04CCF twice, first to print a 4 by 4 lower triangular matrix, and then to print a 5 by 5 upper triangular matrix.

10.1 Program Text

Program Text (x04ccfe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (x04ccfe.r)

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X04CDF : NAG Library, Mark 26

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X04CDF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

X04CDF prints a real triangular matrix stored in a packed one-dimensional array.

2 Specification

SUBROUTINE X04CDF ( UPLO, DIAG, N, A, FORM, TITLE, LABROW, RLABS, LABCOL, CLABS, NCOLS, INDENT, IFAIL)
INTEGER | N, NCOLS, INDENT, IFAIL
REAL (KIND=nag_wp) | A(*)
CHARACTER(*) | FORM, TITLE, RLABS(*), CLABS(*)
CHARACTER(1) | UPLO, DIAG, LABROW, LABCOL

3 Description

X04CDF prints a real triangular matrix stored in packed form, using a format specifier supplied by you. The matrix must be packed by column. The matrix is output to the unit defined by X04ABF.

4 References

None.

5 Arguments

1:   UPLO – CHARACTER(1)Input
On entry: indicates the type of the matrix to be printed
UPLO='L'
The matrix is lower triangular. In this case, the packed array A holds the matrix elements in the following order: 1,1,2,1,…,N,1,2,2,3,2,…,N,2, etc.
UPLO='U'
The matrix is upper triangular. In this case, the packed array A holds the matrix elements in the following order: 1,1,1,2,2,2,1,3,2,3,3,3,1,4, etc.
Constraint: UPLO='L' or 'U'.
2:   DIAG – CHARACTER(1)Input
On entry: indicates whether the diagonal elements of the matrix are to be printed.
DIAG='B'
The diagonal elements of the matrix are not referenced and not printed.
DIAG='U'
The diagonal elements of the matrix are not referenced, but are assumed all to be unity, and are printed as such.
DIAG='N'
The diagonal elements of the matrix are referenced and printed.
Constraint: DIAG='B', 'U' or 'N'.
3:   N – INTEGERInput
On entry: the order of the matrix to be printed.
If N is less than 1, X04CDF will exit immediately after printing TITLE; no row or column labels are printed.
4:   A* – REAL (KIND=nag_wp) arrayInput
Note: the dimension of the array A must be at least max 1,N×N+1/2.
On entry: the matrix to be printed. Note that A must have space for the diagonal elements of the matrix, even if these are not stored.
More precisely,
  • if UPLO='U', the upper triangle of A must be stored with element A ij in A i+j j-1/2 for i≤j;
  • if UPLO='L', the lower triangle of A must be stored with element A ij in A i+2 n-jj-1/2 for i≥j.
If DIAG='U', the diagonal elements of A are assumed to be 1, and are not referenced; the same storage scheme is used whether DIAG='N' or ‘U’.
5:   FORM – CHARACTER(*)Input
On entry: describes the Fortran format code for printing the elements of the matrix A. The format code may be any allowed on the system, whether it is standard Fortran or not. It may or may not be enclosed in brackets.
In addition, there are the following special codes which force X04CDF to choose its own format code:
FORM=' '
X04CDF will choose a format code such that numbers will be printed with an F8.4, an 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.
FORM='*'
X04CDF will choose a format code such that numbers will be printed to as many significant digits as are necessary to distinguish between neighbouring machine numbers. Thus any two numbers that are stored with different internal representations should look different on output. Whether they do in fact look different will depend on the run-time library of the Fortran compiler in use.
By preceding the desired format code by the string ‘MATLAB’, X04CDF will print the matrix such that it can be input into MATLAB, and TITLE will be used as the name of the matrix.
Examples of valid values for FORM are 'F11.4', '1PE13.5', 'G14.5', 'MATLABF11.4', 'MATLAB*'.
Constraint: the character length of the format specifier in FORM must be ≤80.
6:   TITLE – CHARACTER(*)Input
On entry: a title to be printed above the matrix, or name of the matrix.
If TITLE=' ', no title (and no blank line) will be printed.
If TITLE contains more than NCOLS characters, the contents of TITLE will be wrapped onto more than one line, with the break after NCOLS characters.
Any trailing blank characters in TITLE are ignored.
If printing in MATLAB mode, TITLE will be used as the name of the matrix.
7:   LABROW – CHARACTER(1)Input
On entry: indicates the type of labelling to be applied to the rows of the matrix, except in MATLAB mode where LABROW is ignored.
LABROW='N'
Prints no row labels.
LABROW='I'
Prints integer row labels.
LABROW='C'
Prints character labels, which must be supplied in array RLABS.
Constraint: LABROW='N', 'I' or 'C'.
8:   RLABS* – CHARACTER(*) arrayInput
Note: the dimension of the array RLABS must be at least N if LABROW='C', and at least 1 otherwise.
On entry: if LABROW='C', RLABS must contain labels for the rows of the matrix, except in MATLAB mode where RLABS is ignored.
Labels are right-justified when output, in a field which is as wide as necessary to hold the longest row label. Note that this field width is subtracted from the number of usable columns, NCOLS.
9:   LABCOL – CHARACTER(1)Input
On entry: indicates the type of labelling to be applied to the columns of the matrix, except in MATLAB mode where LABCOL is ignored.
LABCOL='N'
Prints no column labels.
LABCOL='I'
Prints integer column labels.
LABCOL='C'
Prints character labels, which must be supplied in array CLABS.
Constraint: LABCOL='N', 'I' or 'C'.
10:   CLABS* – CHARACTER(*) arrayInput
Note: the dimension of the array CLABS must be at least N if LABCOL='C', and at least 1 otherwise.
On entry: if LABCOL='C', CLABS must contain labels for the columns of the matrix, except in MATLAB mode where CLABS is ignored.
Labels are right-justified when output. Any label that is too long for the column width, which is determined by FORM, is truncated.
11:   NCOLS – INTEGERInput
On entry: the maximum output record length. If the number of columns of the matrix is too large to be accommodated in NCOLS characters, the matrix will be printed in parts, containing the largest possible number of matrix columns, and each part separated by a blank line.
NCOLS must be large enough to hold at least one column of the matrix using the format specifier in FORM. If a value less than 0 or greater than 132 is supplied for NCOLS, then the value 80 is used instead.
12:   INDENT – INTEGERInput
On entry: the number of columns by which the matrix (and any title and labels) should be indented. The effective value of NCOLS is reduced by INDENT columns. If a value less than 0 or greater than NCOLS is supplied for INDENT, the value 0 is used instead.
13:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, UPLO≠'L' or 'U'.
IFAIL=2
On entry, DIAG≠'N', 'U' or 'B'.
IFAIL=3
On entry, the format specifier in FORM is more than 80 characters long.
IFAIL=4
The format specifier in FORM cannot be used to output a number. The specifier probably has too wide a field width or contains an illegal edit descriptor.
IFAIL=5
On entry, either LABROW or LABCOL≠'N', 'I' or 'C'.
IFAIL=6
The quantity NCOLS-INDENT-labwid (where labwid is the width needed for the row labels) is not large enough to hold at least one column of the matrix.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X04CDF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example calls X04CDF three times, first to print 4 by 4 lower triangular matrix, and then twice to print a 5 by 5 upper triangular matrix; various options for labelling and formatting are illustrated.

10.1 Program Text

Program Text (x04cdfe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (x04cdfe.r)

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X04CEF : NAG Library, Mark 26

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X04CEF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

X04CEF is an easy-to-use routine to print a real band matrix stored in a packed two-dimensional array.

2 Specification

SUBROUTINE X04CEF ( M, N, KL, KU, A, LDA, TITLE, IFAIL)
INTEGER | M, N, KL, KU, LDA, IFAIL
REAL (KIND=nag_wp) | A(LDA,*)
CHARACTER(*) | TITLE

3 Description

X04CEF prints a real band matrix stored in a packed two-dimensional array. It is an easy-to-use driver for X04CFF. The routine uses default values for the format in which numbers are printed, for labelling the rows and columns, and for output record length.
X04CEF will choose a format code such that numbers will be printed with an F 8.4, an F 11.4 or a 1 PE 13.4 format . The F 8.4 code is chosen if the sizes of all the matrix elements to be printed lie between 0.001 and 1.0. The F 11.4 code is chosen if the sizes of all the matrix elements to be printed lie between 0.001 and 9999.9999. Otherwise the 1 PE 13.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 Arguments

1:   M – INTEGERInput
2:   N – INTEGERInput
On entry: the number of rows and columns of the band matrix, respectively, to be printed.
If either M or N is less than 1, X04CEF will exit immediately after printing TITLE; no row or column labels are printed.
3:   KL – INTEGERInput
On entry: the number of subdiagonals of the band matrix A.
Constraint: KL≥0.
4:   KU – INTEGERInput
On entry: the number of superdiagonals of the band matrix A.
Constraint: KU≥0.
5:   A LDA* – REAL (KIND=nag_wp) arrayInput
Note: the second dimension of the array A must be at least max 1,min M+KU,N.
On entry: the band matrix to be printed.
The matrix is stored in rows 1 to kl+ku+1, more precisely, the element A ij must be stored in
A ku+1+i-j j  for ​max 1,j-ku≤i≤min m,j+kl.
6:   LDA – INTEGERInput
On entry: the first dimension of the array A as declared in the (sub)program from which X04CEF is called.
Constraint: LDA≥KL+KU+1.
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 – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, KL<0.
IFAIL=2
On entry, KU<0.
IFAIL=3
On entry, LDA<KL+KU+1.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X04CEF is not threaded in any implementation.

9 Further Comments

A call to X04CEF is equivalent to a call to X04CFF with the following argument values:

NCOLS = 80
INDENT = 0
LABROW = 'I'
LABCOL = 'I'
FORM = ' '

10 Example

The example program calls X04CEF to print a 5 by 5 band matrix with one subdiagonal and one superdiagonal.

10.1 Program Text

Program Text (x04cefe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (x04cefe.r)

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X04CFF : NAG Library, Mark 26

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X04CFF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

X04CFF prints a real band matrix stored in a packed two-dimensional array.

2 Specification

SUBROUTINE X04CFF ( M, N, KL, KU, A, LDA, FORM, TITLE, LABROW, RLABS, LABCOL, CLABS, NCOLS, INDENT, IFAIL)
INTEGER | M, N, KL, KU, LDA, NCOLS, INDENT, IFAIL
REAL (KIND=nag_wp) | A(LDA,*)
CHARACTER(*) | FORM, TITLE, RLABS(*), CLABS(*)
CHARACTER(1) | LABROW, LABCOL

3 Description

X04CFF prints a real band matrix stored in a packed two-dimensional array, using a format specifier supplied by you. The matrix is output to the unit defined by X04ABF.

4 References

None.

5 Arguments

1:   M – INTEGERInput
2:   N – INTEGERInput
On entry: the number of rows and columns of the band matrix, respectively, to be printed.
If either M or N is less than 1, X04CFF will exit immediately after printing TITLE; no row or column labels are printed.
3:   KL – INTEGERInput
On entry: the number of subdiagonals of the band matrix A.
Constraint: KL≥0.
4:   KU – INTEGERInput
On entry: the number of superdiagonals of the band matrix A.
Constraint: KU≥0.
5:   A LDA* – REAL (KIND=nag_wp) arrayInput
Note: the second dimension of the array A must be at least max 1,min M+KU,N.
On entry: the band matrix to be printed.
The matrix is stored in rows 1 to kl+ku+1, more precisely, the element A ij must be stored in
A ku+1+i-j j  for ​max 1,j-ku≤i≤min m,j+kl.
6:   LDA – INTEGERInput
On entry: the first dimension of the array A as declared in the (sub)program from which X04CFF is called.
Constraint: LDA≥KL+KU+1.
7:   FORM – CHARACTER(*)Input
On entry: describes the Fortran format code for printing the elements of the matrix A. The format code may be any allowed on the system, whether it is standard Fortran or not. It may or may not be enclosed in brackets.
In addition, there are the following special codes which force X04CFF to choose its own format code:
FORM=' '
X04CFF will choose a format code such that numbers will be printed with an F8.4, an 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.
FORM='*'
X04CFF will choose a format code such that numbers will be printed to as many significant digits as are necessary to distinguish between neighbouring machine numbers. Thus any two numbers that are stored with different internal representations should look different on output. Whether they do in fact look different will depend on the run-time library of the Fortran compiler in use.
By preceding the desired format code by the string ‘MATLAB’, X04CFF will print the matrix such that it can be input into MATLAB, and TITLE will be used as the name of the matrix.
Examples of valid values for FORM are 'F11.4', '1PE13.5', 'G14.5', 'MATLABF11.4', 'MATLAB*'.
Constraint: the character length of the format specifier in FORM must be ≤80.
8:   TITLE – CHARACTER(*)Input
On entry: a title to be printed above the matrix, or name of the matrix.
If TITLE=' ', no title (and no blank line) will be printed.
If TITLE contains more than NCOLS characters, the contents of TITLE will be wrapped onto more than one line, with the break after NCOLS characters.
Any trailing blank characters in TITLE are ignored.
If printing in MATLAB mode, TITLE will be used as the name of the matrix.
9:   LABROW – CHARACTER(1)Input
On entry: indicates the type of labelling to be applied to the rows of the matrix, except in MATLAB mode where LABROW is ignored.
LABROW='N'
Prints no row labels.
LABROW='I'
Prints integer row labels.
LABROW='C'
Prints character labels, which must be supplied in array RLABS.
Constraint: LABROW='N', 'I' or 'C'.
10:   RLABS* – CHARACTER(*) arrayInput
Note: the dimension of the array RLABS must be at least M if LABROW='C', and at least 1 otherwise.
On entry: if LABROW='C', RLABS must contain labels for the rows of the matrix, except in MATLAB mode where RLABS is ignored.
Labels are right-justified when output, in a field which is as wide as necessary to hold the longest row label. Note that this field width is subtracted from the number of usable columns, NCOLS.
11:   LABCOL – CHARACTER(1)Input
On entry: indicates the type of labelling to be applied to the columns of the matrix, except in MATLAB mode where LABCOL is ignored.
LABCOL='N'
Prints no column labels.
LABCOL='I'
Prints integer column labels.
LABCOL='C'
Prints character labels, which must be supplied in array CLABS.
Constraint: LABCOL='N', 'I' or 'C'.
12:   CLABS* – CHARACTER(*) arrayInput
Note: the dimension of the array CLABS must be at least N if LABCOL='C', and at least 1 otherwise.
On entry: if LABCOL='C', CLABS must contain labels for the columns of the matrix, except in MATLAB mode where CLABS is ignored.
Labels are right-justified when output. Any label that is too long for the column width, which is determined by FORM, is truncated.
13:   NCOLS – INTEGERInput
On entry: the maximum output record length. If the number of columns of the matrix is too large to be accommodated in NCOLS characters, the matrix will be printed in parts, containing the largest possible number of matrix columns, and each part separated by a blank line.
NCOLS must be large enough to hold at least one column of the matrix using the format specifier in FORM. If a value less than 0 or greater than 132 is supplied for NCOLS, then the value 80 is used instead.
14:   INDENT – INTEGERInput
On entry: the number of columns by which the matrix (and any title and labels) should be indented. The effective value of NCOLS is reduced by INDENT columns. If a value less than 0 or greater than NCOLS is supplied for INDENT, the value 0 is used instead.
15:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, KL<0.
IFAIL=2
On entry, KU<0.
IFAIL=3
On entry, LDA<KL+KU+1.
IFAIL=4
On entry, the format specifier in FORM is more than 80 characters long.
IFAIL=5
The format specifier in FORM cannot be used to output a number. The specifier probably has too wide a field width or contains an illegal edit descriptor.
IFAIL=6
On entry, either LABROW or LABCOL≠'N', 'I' or 'C'.
IFAIL=7
The quantity NCOLS-INDENT-labwid (where labwid is the width needed for the row labels) is not large enough to hold at least one column of the matrix.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X04CFF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example calls X04CFF three times, to print 5 by 5 matrices of different bandwidths; various options for labelling and formatting are illustrated.

10.1 Program Text

Program Text (x04cffe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (x04cffe.r)

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X04 Chapter Contents : NAG Library Manual, Mark 26

X04 Chapter Introduction

NAG Library Chapter Contents

X04 – Input/Output Utilities

X04 Chapter Introduction – a description of the Chapter and an overview of the algorithms available

Routine Name | Mark of Introduction | Purpose
X04AAF Example Text | 7 | nagf_file_set_unit_error Return or set unit number for error messages
X04ABF Example Text | 7 | nagf_file_set_unit_advisory Return or set unit number for advisory messages
X04ACF Example Text | 19 | nagf_file_open Open unit number for reading, writing or appending, and associate unit with named file
X04ADF Example Text | 19 | nagf_file_close Close file associated with given unit number
X04BAF Example Text | 12 | nagf_file_line_write Write formatted record to external file
X04BBF Example Text Example Data | 12 | nagf_file_line_read Read formatted record from external file
X04CAF Example Text | 14 | nagf_file_print_matrix_real_gen Print real general matrix (easy-to-use)
X04CBF Example Text | 14 | nagf_file_print_matrix_real_gen_comp Print real general matrix (comprehensive)
X04CCF Example Text | 14 | nagf_file_print_matrix_real_packed Print real packed triangular matrix (easy-to-use)
X04CDF Example Text | 14 | nagf_file_print_matrix_real_packed_comp Print real packed triangular matrix (comprehensive)
X04CEF Example Text | 14 | nagf_file_print_matrix_real_band Print real packed banded matrix (easy-to-use)
X04CFF Example Text | 14 | nagf_file_print_matrix_real_band_comp Print real packed banded matrix (comprehensive)
X04DAF Example Text | 14 | nagf_file_print_matrix_complex_gen Print complex general matrix (easy-to-use)
X04DBF Example Text | 14 | nagf_file_print_matrix_complex_gen_comp Print complex general matrix (comprehensive)
X04DCF Example Text | 14 | nagf_file_print_matrix_complex_packed Print complex packed triangular matrix (easy-to-use)
X04DDF Example Text | 14 | nagf_file_print_matrix_complex_packed_comp Print complex packed triangular matrix (comprehensive)
X04DEF Example Text | 14 | nagf_file_print_matrix_complex_band Print complex packed banded matrix (easy-to-use)
X04DFF Example Text | 14 | nagf_file_print_matrix_complex_band_comp Print complex packed banded matrix (comprehensive)
X04EAF Example Text | 14 | nagf_file_print_matrix_integer Print integer matrix (easy-to-use)
X04EBF Example Text | 14 | nagf_file_print_matrix_integer_comp Print integer matrix (comprehensive)
X04 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X04DAF : NAG Library, Mark 26

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X04DAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

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, IFAIL)
INTEGER | M, N, LDA, IFAIL
COMPLEX (KIND=nag_wp) | A(LDA,*)
CHARACTER(*) | TITLE
CHARACTER(1) | MATRIX, DIAG

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 an F 8.4, an F 11.4 or a 1 PE 13.4 format. The F 8.4 code is chosen if the sizes of all the matrix elements to be printed lie between 0.001 and 1.0. The F 11.4 code is chosen if the sizes of all the matrix elements to be printed lie between 0.001 and 9999.9999. Otherwise the 1 PE 13.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 Arguments

1:   MATRIX – CHARACTER(1)Input
On entry: indicates the part of the matrix to be printed.
MATRIX='G'
The whole of the rectangular matrix.
MATRIX='L'
The lower triangle of the matrix, or the lower trapezium if the matrix has more rows than columns.
MATRIX='U'
The upper triangle of the matrix, or the upper trapezium if the matrix has more columns than rows.
Constraint: MATRIX='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.
DIAG='B'
The diagonal elements of the matrix are not referenced and not printed.
DIAG='U'
The diagonal elements of the matrix are not referenced, but are assumed all to be unity, and are printed as such.
DIAG='N'
The diagonal elements of the matrix are referenced and printed.
If MATRIX='G', then DIAG need not be set.
Constraint: if MATRIX≠'G', DIAG='B', 'U' or 'N'.
3:   M – INTEGERInput
4:   N – INTEGERInput
On entry: the number of rows and columns of the matrix, respectively, to be printed.
If either 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=nag_wp) arrayInput
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 arguments MATRIX and DIAG, need be set.
6:   LDA – INTEGERInput
On entry: the first dimension of the array A as declared in the (sub)program from which X04DAF is called.
Constraint: LDA≥max 1,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 – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
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.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X04DAF is not threaded in any implementation.

9 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'
FORM = ' '
USEFRM = 'A'

10 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.

10.1 Program Text

Program Text (x04dafe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (x04dafe.r)

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X04DBF : NAG Library, Mark 26

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X04DBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

X04DBF prints a complex matrix stored in a two-dimensional array.

2 Specification

SUBROUTINE X04DBF ( MATRIX, DIAG, M, N, A, LDA, USEFRM, FORM, TITLE, LABROW, RLABS, LABCOL, CLABS, NCOLS, INDENT, IFAIL)
INTEGER | M, N, LDA, NCOLS, INDENT, IFAIL
COMPLEX (KIND=nag_wp) | A(LDA,*)
CHARACTER(*) | FORM, TITLE, RLABS(*), CLABS(*)
CHARACTER(1) | MATRIX, DIAG, USEFRM, LABROW, LABCOL

3 Description

X04DBF prints a complex matrix, or part of it, using a format specifier supplied by you. The matrix is output to the unit defined by X04ABF.

4 References

None.

5 Arguments

1:   MATRIX – CHARACTER(1)Input
On entry: indicates the part of the matrix to be printed.
MATRIX='G'
The whole of the rectangular matrix.
MATRIX='L'
The lower triangle of the matrix, or the lower trapezium if the matrix has more rows than columns.
MATRIX='U'
The upper triangle of the matrix, or the upper trapezium if the matrix has more columns than rows.
Constraint: MATRIX='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.
DIAG='B'
The diagonal elements of the matrix are not referenced and not printed.
DIAG='U'
The diagonal elements of the matrix are not referenced, but are assumed all to be unity, and are printed as such.
DIAG='N'
The diagonal elements of the matrix are referenced and printed.
If MATRIX='G', then DIAG need not be set.
Constraint: if MATRIX≠'G', DIAG='B', 'U' or 'N'.
3:   M – INTEGERInput
4:   N – INTEGERInput
On entry: the number of rows and columns of the matrix, respectively, to be printed.
If either M or N is less than 1, X04DBF will exit immediately after printing TITLE; no row or column labels are printed.
5:   A LDA* – COMPLEX (KIND=nag_wp) arrayInput
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 arguments MATRIX and DIAG, need be set.
6:   LDA – INTEGERInput
On entry: the first dimension of the array A as declared in the (sub)program from which X04DBF is called.
Constraint: LDA≥max 1,M.
7:   USEFRM – CHARACTER(1)Input
On entry: indicates how the value of FORM is to be used to print matrix elements, except in MATLAB mode where USEFRM is ignored.
USEFRM='A'
The format code in FORM is assumed to contain a single real edit-descriptor which is to be used to print the real and imaginary parts of each complex number one above the other. Each row of the matrix is separated by a blank line, and any row labels are attached only to the real parts. This option means that about twice as many columns can be fitted into NCOLS characters than if any other USEFRM option is used. A typical value of FORM for this USEFRM option might be 'E13.4', '*' or ' '.
USEFRM='B'
The format code in FORM is assumed to contain a single edit-descriptor such as 'E13.4', '*' or ' ' which is used to print the real and imaginary parts of each complex number separated by a comma, and surrounded by brackets. Thus a matrix element printed with this USEFRM option might look like this: 12.345,-11.323.
USEFRM='D'
The format code in FORM is used unaltered to print a complex number. This USEFRM option allows you flexibility to specify exactly how the number is printed. With this option for USEFRM and a suitable value for FORM it is possible, for example, to print a complex number in the form 0.123+3.214 i or 0.123E−02,0.234E−01. See Section 10 for an example illustrating this option.
Constraint: USEFRM='A', 'B' or 'D'.
8:   FORM – CHARACTER(*)Input
On entry: describes the Fortran format code that is used in conjunction with USEFRM for printing the elements of the matrix A. The format code may be any allowed on the system, whether it is standard Fortran or not. It may or may not be enclosed in brackets.
In addition, there are the following special codes which force X04DBF to choose its own format code:
FORM=' '
X04DBF will choose a format code such that numbers will be printed with an F8.4, an F11.4 or a 1PE13.4 format. The F8.4 code is chosen if the sizes of the real and imaginary parts 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 numbers to be printed lie between 0.001 and 9999.9999. Otherwise the 1PE13.4 code is chosen.
FORM='*'
X04DBF will choose a format code such that numbers will be printed to as many significant digits as are necessary to distinguish between neighbouring machine numbers. Thus any two numbers that are stored with different internal representations should look different on output. Whether they do in fact look different will depend on the run-time library of the Fortran compiler in use.
By preceding the desired format code by the string ‘MATLAB’, X04DBF will print the matrix such that it can be input into MATLAB, and TITLE will be used as the name of the matrix.
More complicated values of FORM, to print a complex number in a desired form, may be used. See the description of argument USEFRM for more details.
Examples of valid values for FORM are '(F11.4)', '1P,2E13.5', 'MATLABF11.4', 'MATLAB*'.
Constraint: the character length of the format specifier in FORM must be ≤80.
9:   TITLE – CHARACTER(*)Input
On entry: a title to be printed above the matrix, or name of the matrix.
If TITLE=' ', no title (and no blank line) will be printed.
If TITLE contains more than NCOLS characters, the contents of TITLE will be wrapped onto more than one line, with the break after NCOLS characters.
Any trailing blank characters in TITLE are ignored.
If printing in MATLAB mode, TITLE will be used as the name of the matrix.
10:   LABROW – CHARACTER(1)Input
On entry: indicates the type of labelling to be applied to the rows of the matrix, except in MATLAB mode where LABROW is ignored.
LABROW='N'
Prints no row labels.
LABROW='I'
Prints integer row labels.
LABROW='C'
Prints character labels, which must be supplied in array RLABS.
Constraint: LABROW='N', 'I' or 'C'.
11:   RLABS* – CHARACTER(*) arrayInput
Note: the dimension of the array RLABS must be at least M if LABROW='C', and at least 1 otherwise.
On entry: if LABROW='C', RLABS must contain labels for the rows of the matrix, except in MATLAB mode where RLABS is ignored.
Labels are right-justified when output, in a field which is as wide as necessary to hold the longest row label. Note that this field width is subtracted from the number of usable columns, NCOLS.
12:   LABCOL – CHARACTER(1)Input
On entry: indicates the type of labelling to be applied to the columns of the matrix, except in MATLAB mode where LABCOL is ignored.
LABCOL='N'
Prints no column labels.
LABCOL='I'
Prints integer column labels.
LABCOL='C'
Prints character labels, which must be supplied in array CLABS.
Constraint: LABCOL='N', 'I' or 'C'.
13:   CLABS* – CHARACTER(*) arrayInput
Note: the dimension of the array CLABS must be at least N if LABCOL='C', and at least 1 otherwise.
On entry: if LABCOL='C', CLABS must contain labels for the columns of the matrix, except in MATLAB mode where CLABS is ignored.
Labels are right-justified when output. Any label that is too long for the column width, which is determined by FORM, is truncated.
14:   NCOLS – INTEGERInput
On entry: the maximum output record length. If the number of columns of the matrix is too large to be accommodated in NCOLS characters, the matrix will be printed in parts, containing the largest possible number of matrix columns, and each part separated by a blank line.
NCOLS must be large enough to hold at least one column of the matrix using the format specifier in FORM. If a value less than 0 or greater than 132 is supplied for NCOLS, then the value 80 is used instead.
15:   INDENT – INTEGERInput
On entry: the number of columns by which the matrix (and any title and labels) should be indented. The effective value of NCOLS is reduced by INDENT columns. If a value less than 0 or greater than NCOLS is supplied for INDENT, the value 0 is used instead.
16:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
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.
IFAIL=4
On entry, USEFRM≠'A', 'B' or 'D'.
IFAIL=5
On entry, the format specifier in FORM is more than 80 characters long.
IFAIL=6
The format specifier in FORM cannot be used to output a number. The specifier probably has too wide a field width or contains an illegal edit descriptor.
IFAIL=7
On entry, either LABROW or LABCOL≠'N', 'I' or 'C'.
IFAIL=8
The quantity NCOLS-INDENT-labwid (where labwid is the width needed for the row labels) is not large enough to hold at least one column of the matrix.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X04DBF is not threaded in any implementation.

9 Further Comments

X04DBF may be used to print a vector, either as a row or as a column. The following code fragment illustrates possible calls.
      complex*16 A(4)
      CHARACTER*1 RLABS(1), CLABS(1)
!     Print vector A as a column vector.
      LDA = 4
      IFAIL = 0
      CALL X04DBF('G','X',1,4,A,LDA,'B',' ',' ','I',RLABS, &
                  'N',CLABS,80,0,IFAIL)
!     Print vector A as a row vector.
      LDA = 1
      IFAIL = 0
      CALL X04DBF('G','X',4,1,A,LDA,'B',' ',' ','N',RLABS, &
                  'I',CLABS,80,0,IFAIL)

10 Example

The example program calls X04DBF three times, first to print a 3 by 4 rectangular matrix, next to print a 4 by 4 upper triangular matrix, and then to print a 3 by 4 lower triangular matrix; various options for labelling and formatting are illustrated.

10.1 Program Text

Program Text (x04dbfe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (x04dbfe.r)

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X04DCF : NAG Library, Mark 26

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X04DCF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

X04DCF is an easy-to-use routine to print a complex triangular matrix stored in a packed one-dimensional array.

2 Specification

SUBROUTINE X04DCF ( UPLO, DIAG, N, A, TITLE, IFAIL)
INTEGER | N, IFAIL
COMPLEX (KIND=nag_wp) | A(*)
CHARACTER(*) | TITLE
CHARACTER(1) | UPLO, DIAG

3 Description

X04DCF prints a complex triangular matrix stored in packed form. It is an easy-to-use driver for X04DDF. The routine uses default values for the format in which numbers are printed, for labelling the rows and columns, and for output record length. The matrix must be packed by column.
X04DCF will choose a format code such that numbers will be printed with an F 8.4, an F 11.4 or a 1 PE 13.4 format . The F 8.4 code is chosen if the sizes of all the matrix elements to be printed lie between 0.001 and 1.0. The F 11.4 code is chosen if the sizes of all the matrix elements to be printed lie between 0.001 and 9999.9999. Otherwise the 1 PE 13.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 Arguments

1:   UPLO – CHARACTER(1)Input
On entry: indicates the type of the matrix to be printed
UPLO='L'
The matrix is lower triangular. In this case, the packed array A holds the matrix elements in the following order: 1,1,2,1,…,N,1,2,2,3,2,…,N,2, etc.
UPLO='U'
The matrix is upper triangular. In this case, the packed array A holds the matrix elements in the following order: 1,1,1,2,2,2,1,3,2,3,3,3,1,4, etc.
Constraint: UPLO='L' or 'U'.
2:   DIAG – CHARACTER(1)Input
On entry: indicates whether the diagonal elements of the matrix are to be printed.
DIAG='B'
The diagonal elements of the matrix are not referenced and not printed.
DIAG='U'
The diagonal elements of the matrix are not referenced, but are assumed all to be unity, and are printed as such.
DIAG='N'
The diagonal elements of the matrix are referenced and printed.
Constraint: DIAG='B', 'U' or 'N'.
3:   N – INTEGERInput
On entry: the order of the matrix to be printed.
If N is less than 1, X04DCF will exit immediately after printing TITLE; no row or column labels are printed.
4:   A* – COMPLEX (KIND=nag_wp) arrayInput
Note: the dimension of the array A must be at least max 1,N×N+1/2.
On entry: the matrix to be printed. Note that A must have space for the diagonal elements of the matrix, even if these are not stored.
More precisely,
  • if UPLO='U', the upper triangle of A must be stored with element A ij in A i+j j-1/2 for i≤j;
  • if UPLO='L', the lower triangle of A must be stored with element A ij in A i+2 n-jj-1/2 for i≥j.
If DIAG='U', the diagonal elements of A are assumed to be 1, and are not referenced; the same storage scheme is used whether DIAG='N' or ‘U’.
5:   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.
6:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, UPLO≠'L' or 'U'.
IFAIL=2
On entry, DIAG≠'N', 'U' or 'B'.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X04DCF is not threaded in any implementation.

9 Further Comments

A call to X04DCF is equivalent to a call to X04DDF with the following argument values:

NCOLS = 80
INDENT = 0
LABROW = 'I'
LABCOL = 'I'
FORM = ' '
USEFRM = 'A'

10 Example

The example program calls X04DCF twice, first to print a 3 by 3 lower triangular matrix, and then to print a 4 by 4 upper triangular matrix.

10.1 Program Text

Program Text (x04dcfe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (x04dcfe.r)

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X04DDF : NAG Library, Mark 26

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X04DDF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

X04DDF prints a complex triangular matrix stored in a packed one-dimensional array.

2 Specification

SUBROUTINE X04DDF ( UPLO, DIAG, N, A, USEFRM, FORM, TITLE, LABROW, RLABS, LABCOL, CLABS, NCOLS, INDENT, IFAIL)
INTEGER | N, NCOLS, INDENT, IFAIL
COMPLEX (KIND=nag_wp) | A(*)
CHARACTER(*) | FORM, TITLE, RLABS(*), CLABS(*)
CHARACTER(1) | UPLO, DIAG, USEFRM, LABROW, LABCOL

3 Description

X04DDF prints a complex triangular matrix stored in packed form, using a format specifier supplied by you. The matrix must be packed by column. The matrix is output to the unit defined by X04ABF.

4 References

None.

5 Arguments

1:   UPLO – CHARACTER(1)Input
On entry: indicates the type of the matrix to be printed
UPLO='L'
The matrix is lower triangular. In this case, the packed array A holds the matrix elements in the following order: 1,1,2,1,…,N,1,2,2,3,2,…,N,2, etc.
UPLO='U'
The matrix is upper triangular. In this case, the packed array A holds the matrix elements in the following order: 1,1,1,2,2,2,1,3,2,3,3,3,1,4, etc.
Constraint: UPLO='L' or 'U'.
2:   DIAG – CHARACTER(1)Input
On entry: indicates whether the diagonal elements of the matrix are to be printed.
DIAG='B'
The diagonal elements of the matrix are not referenced and not printed.
DIAG='U'
The diagonal elements of the matrix are not referenced, but are assumed all to be unity, and are printed as such.
DIAG='N'
The diagonal elements of the matrix are referenced and printed.
Constraint: DIAG='B', 'U' or 'N'.
3:   N – INTEGERInput
On entry: the number of rows and columns of the matrix to be printed.
If N is less than 1, X04DDF will exit immediately after printing TITLE; no row or column labels are printed.
4:   A* – COMPLEX (KIND=nag_wp) arrayInput
Note: the dimension of the array A must be at least max 1,N×N+1/2.
On entry: the matrix to be printed. Note that A must have space for the diagonal elements of the matrix, even if these are not stored.
More precisely,
  • if UPLO='U', the upper triangle of A must be stored with element A ij in A i+j j-1/2 for i≤j;
  • if UPLO='L', the lower triangle of A must be stored with element A ij in A i+2 n-jj-1/2 for i≥j.
If DIAG='U', the diagonal elements of A are assumed to be 1, and are not referenced; the same storage scheme is used whether DIAG='N' or ‘U’.
5:   USEFRM – CHARACTER(1)Input
On entry: indicates how the value of FORM is to be used to print matrix elements, except in MATLAB mode where USEFRM is ignored.
USEFRM='A'
The format code in FORM is assumed to contain a single real edit-descriptor which is to be used to print the real and imaginary parts of each complex number one above the other. Each row of the matrix is separated by a blank line, and any row labels are attached only to the real parts. This option means that about twice as many columns can be fitted into NCOLS characters than if any other USEFRM option is used. A typical value of FORM for this USEFRM option might be 'E13.4', '*' or ' '.
USEFRM='B'
The format code in FORM is assumed to contain a single edit-descriptor such as 'E13.4', '*' or ' ' which is used to print the real and imaginary parts of each complex number separated by a comma, and surrounded by brackets. Thus a matrix element printed with this USEFRM option might look like this: 12.345,-11.323.
USEFRM='D'
The format code in FORM is used unaltered to print a complex number. This USEFRM option allows you flexibility to specify exactly how the number is printed. With this option for USEFRM and a suitable value for FORM it is possible, for example, to print a complex number in the form 0.123+3.214 i or 0.123E−02,0.234E−01. See Section 10 for an example illustrating this option.
Constraint: USEFRM='A', 'B' or 'D'.
6:   FORM – CHARACTER(*)Input
On entry: describes the Fortran format code that is used in conjunction with USEFRM for printing the elements of the matrix A. The format code may be any allowed on the system, whether it is standard Fortran or not. It may or may not be enclosed in brackets.
In addition, there are the following special codes which force X04DDF to choose its own format code:
FORM=' '
X04DDF will choose a format code such that numbers will be printed with an F8.4, an F11.4 or a 1PE13.4 format. The F8.4 code is chosen if the sizes of the real and imaginary parts 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 numbers to be printed lie between 0.001 and 9999.9999. Otherwise the 1PE13.4 code is chosen.
FORM='*'
X04DDF will choose a format code such that numbers will be printed to as many significant digits as are necessary to distinguish between neighbouring machine numbers. Thus any two numbers that are stored with different internal representations should look different on output. Whether they do in fact look different will depend on the run-time library of the Fortran compiler in use.
By preceding the desired format code by the string ‘MATLAB’, X04DDF will print the matrix such that it can be input into MATLAB, and TITLE will be used as the name of the matrix.
More complicated values of FORM, to print a complex number in a desired form, may be used. See the description of argument USEFRM for more details.
Examples of valid values for FORM are '(F11.4)', '1P,2E13.5', 'MATLABF11.4', 'MATLAB*'.
Constraint: the character length of the format specifier in FORM must be ≤80.
7:   TITLE – CHARACTER(*)Input
On entry: a title to be printed above the matrix, or name of the matrix.
If TITLE=' ', no title (and no blank line) will be printed.
If TITLE contains more than NCOLS characters, the contents of TITLE will be wrapped onto more than one line, with the break after NCOLS characters.
Any trailing blank characters in TITLE are ignored.
If printing in MATLAB mode, TITLE will be used as the name of the matrix.
8:   LABROW – CHARACTER(1)Input
On entry: indicates the type of labelling to be applied to the rows of the matrix, except in MATLAB mode where LABROW is ignored.
LABROW='N'
Prints no row labels.
LABROW='I'
Prints integer row labels.
LABROW='C'
Prints character labels, which must be supplied in array RLABS.
Constraint: LABROW='N', 'I' or 'C'.
9:   RLABS* – CHARACTER(*) arrayInput
Note: the dimension of the array RLABS must be at least N if LABROW='C', and at least 1 otherwise.
On entry: if LABROW='C', RLABS must contain labels for the rows of the matrix, except in MATLAB mode where RLABS is ignored.
Labels are right-justified when output, in a field which is as wide as necessary to hold the longest row label. Note that this field width is subtracted from the number of usable columns, NCOLS.
10:   LABCOL – CHARACTER(1)Input
On entry: indicates the type of labelling to be applied to the columns of the matrix, except in MATLAB mode where LABCOL is ignored.
LABCOL='N'
Prints no column labels.
LABCOL='I'
Prints integer column labels.
LABCOL='C'
Prints character labels, which must be supplied in array CLABS.
Constraint: LABCOL='N', 'I' or 'C'.
11:   CLABS* – CHARACTER(*) arrayInput
Note: the dimension of the array CLABS must be at least N if LABCOL='C', and at least 1 otherwise.
On entry: if LABCOL='C', CLABS must contain labels for the columns of the matrix, except in MATLAB mode where CLABS is ignored.
Labels are right-justified when output. Any label that is too long for the column width, which is determined by FORM, is truncated.
12:   NCOLS – INTEGERInput
On entry: the maximum output record length. If the number of columns of the matrix is too large to be accommodated in NCOLS characters, the matrix will be printed in parts, containing the largest possible number of matrix columns, and each part separated by a blank line.
NCOLS must be large enough to hold at least one column of the matrix using the format specifier in FORM. If a value less than 0 or greater than 132 is supplied for NCOLS, then the value 80 is used instead.
13:   INDENT – INTEGERInput
On entry: the number of columns by which the matrix (and any title and labels) should be indented. The effective value of NCOLS is reduced by INDENT columns. If a value less than 0 or greater than NCOLS is supplied for INDENT, the value 0 is used instead.
14:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, UPLO≠'L' or 'U'.
IFAIL=2
On entry, DIAG≠'N', 'U' or 'B'.
IFAIL=3
On entry, USEFRM≠'A', 'B' or 'D'.
IFAIL=4
On entry, the format specifier in FORM is more than 80 characters long.
IFAIL=5
The format specifier in FORM cannot be used to output a number. The specifier probably has too wide a field width or contains an illegal edit descriptor.
IFAIL=6
On entry, either LABROW or LABCOL≠'N', 'I' or 'C'.
IFAIL=7
The quantity NCOLS-INDENT-labwid (where labwid is the width needed for the row labels) is not large enough to hold at least one column of the matrix.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X04DDF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example program calls X04DDF three times, first to print a 4 by 4 lower triangular matrix, and then twice to print a 4 by 4 upper triangular matrix, various options for labelling and formatting are illustrated.

10.1 Program Text

Program Text (x04ddfe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (x04ddfe.r)

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X04DEF : NAG Library, Mark 26

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X04DEF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

X04DEF is an easy-to-use routine to print a complex band matrix stored in a packed two-dimensional array.

2 Specification

SUBROUTINE X04DEF ( M, N, KL, KU, A, LDA, TITLE, IFAIL)
INTEGER | M, N, KL, KU, LDA, IFAIL
COMPLEX (KIND=nag_wp) | A(LDA,*)
CHARACTER(*) | TITLE

3 Description

X04DEF prints a complex band matrix stored in a packed two-dimensional array. It is an easy-to-use driver for X04DFF. The routine uses default values for the format in which numbers are printed, for labelling the rows and columns, and for output record length.
X04DEF will choose a format code such that numbers will be printed with an F 8.4, an F 11.4 or a 1 PE 13.4 format. The F 8.4 code is chosen if the sizes of all the matrix elements to be printed lie between 0.001 and 1.0. The F 11.4 code is chosen if the sizes of all the matrix elements to be printed lie between 0.001 and 9999.9999. Otherwise the 1 PE 13.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 Arguments

1:   M – INTEGERInput
2:   N – INTEGERInput
On entry: the number of rows and columns of the band matrix, respectively, to be printed.
If either M or N is less than 1, X04DEF will exit immediately after printing TITLE; no row or column labels are printed.
3:   KL – INTEGERInput
On entry: the number of subdiagonals of the band matrix A.
Constraint: KL≥0.
4:   KU – INTEGERInput
On entry: the number of superdiagonals of the band matrix A.
Constraint: KU≥0.
5:   A LDA* – COMPLEX (KIND=nag_wp) arrayInput
Note: the second dimension of the array A must be at least max 1,min M+KU,N.
On entry: the band matrix to be printed.
The matrix is stored in rows 1 to kl+ku+1, more precisely, the element A ij must be stored in
A ku+1+i-j j  for ​max 1,j-ku≤i≤min m,j+kl.
6:   LDA – INTEGERInput
On entry: the first dimension of the array A as declared in the (sub)program from which X04DEF is called.
Constraint: LDA≥KL+KU+1.
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 – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, KL<0.
IFAIL=2
On entry, KU<0.
IFAIL=3
On entry, LDA<KL+KU+1.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X04DEF is not threaded in any implementation.

9 Further Comments

A call to X04DEF is equivalent to a call to X04DFF with the following argument values:

NCOLS = 80
INDENT = 0
LABROW = 'I'
LABCOL = 'I'
FORM = ' '
USEFRM = 'A'

10 Example

This example program calls X04DEF to print a 5 by 5 band matrix with one subdiagonal and one superdiagonal.

10.1 Program Text

Program Text (x04defe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (x04defe.r)

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X04DFF : NAG Library, Mark 26

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X04DFF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

X04DFF prints a complex band matrix stored in a packed two-dimensional array.

2 Specification

SUBROUTINE X04DFF ( M, N, KL, KU, A, LDA, USEFRM, FORM, TITLE, LABROW, RLABS, LABCOL, CLABS, NCOLS, INDENT, IFAIL)
INTEGER | M, N, KL, KU, LDA, NCOLS, INDENT, IFAIL
COMPLEX (KIND=nag_wp) | A(LDA,*)
CHARACTER(*) | FORM, TITLE, RLABS(*), CLABS(*)
CHARACTER(1) | USEFRM, LABROW, LABCOL

3 Description

X04DFF prints a complex band matrix stored in a packed two-dimensional array, using a format specifier supplied by you. The matrix is output to the unit defined by X04ABF.

4 References

None.

5 Arguments

1:   M – INTEGERInput
2:   N – INTEGERInput
On entry: the number of rows and columns of the band matrix, respectively, to be printed.
If either M or N is less than 1, X04DFF will exit immediately after printing TITLE; no row or column labels are printed.
3:   KL – INTEGERInput
On entry: the number of subdiagonals of the band matrix A.
Constraint: KL≥0.
4:   KU – INTEGERInput
On entry: the number of superdiagonals of the band matrix A.
Constraint: KU≥0.
5:   A LDA* – COMPLEX (KIND=nag_wp) arrayInput
Note: the second dimension of the array A must be at least max 1,min M+KU,N.
On entry: the band matrix to be printed.
The matrix is stored in rows 1 to kl+ku+1, more precisely, the element A ij must be stored in
A ku+1+i-j j  for ​max 1,j-ku≤i≤min m,j+kl.
6:   LDA – INTEGERInput
On entry: the first dimension of the array A as declared in the (sub)program from which X04DFF is called.
Constraint: LDA≥KL+KU+1.
7:   USEFRM – CHARACTER(1)Input
On entry: indicates how the value of FORM is to be used to print matrix elements, except in MATLAB mode where USEFRM is ignored.
USEFRM='A'
The format code in FORM is assumed to contain a single real edit-descriptor which is to be used to print the real and imaginary parts of each complex number one above the other. Each row of the matrix is separated by a blank line, and any row labels are attached only to the real parts. This option means that about twice as many columns can be fitted into NCOLS characters than if any other USEFRM option is used. A typical value of FORM for this USEFRM option might be 'E13.4', '*' or ' '.
USEFRM='B'
The format code in FORM is assumed to contain a single edit-descriptor such as 'E13.4', '*' or ' ' which is used to print the real and imaginary parts of each complex number separated by a comma, and surrounded by brackets. Thus a matrix element printed with this USEFRM option might look like this: 12.345,-11.323.
USEFRM='D'
The format code in FORM is used unaltered to print a complex number. This USEFRM option allows you flexibility to specify exactly how the number is printed. With this option for USEFRM and a suitable value for FORM it is possible, for example, to print a complex number in the form 0.123+3.214 i or 0.123E−02,0.234E−01. See Section 10 for an example illustrating this option.
Constraint: USEFRM='A', 'B' or 'D'.
8:   FORM – CHARACTER(*)Input
On entry: describes the Fortran format code that is used in conjunction with USEFRM for printing the elements of the matrix A. The format code may be any allowed on the system, whether it is standard Fortran or not. It may or may not be enclosed in brackets.
In addition, there are the following special codes which force X04DFF to choose its own format code:
FORM=' '
X04DFF will choose a format code such that numbers will be printed with an F8.4, an F11.4 or a 1PE13.4 format. The F8.4 code is chosen if the sizes of the real and imaginary parts 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 numbers to be printed lie between 0.001 and 9999.9999. Otherwise the 1PE13.4 code is chosen.
FORM='*'
X04DFF will choose a format code such that numbers will be printed to as many significant digits as are necessary to distinguish between neighbouring machine numbers. Thus any two numbers that are stored with different internal representations should look different on output. Whether they do in fact look different will depend on the run-time library of the Fortran compiler in use.
By preceding the desired format code by the string ‘MATLAB’, X04DFF will print the matrix such that it can be input into MATLAB, and TITLE will be used as the name of the matrix.
More complicated values of FORM, to print a complex number in a desired form, may be used. See the description of argument USEFRM for more details.
Examples of valid values for FORM are '(F11.4)', '1P,2E13.5', 'MATLABF11.4', 'MATLAB*'.
Constraint: the character length of the format specifier in FORM must be ≤80.
9:   TITLE – CHARACTER(*)Input
On entry: a title to be printed above the matrix, or name of the matrix.
If TITLE=' ', no title (and no blank line) will be printed.
If TITLE contains more than NCOLS characters, the contents of TITLE will be wrapped onto more than one line, with the break after NCOLS characters.
Any trailing blank characters in TITLE are ignored.
If printing in MATLAB mode, TITLE will be used as the name of the matrix.
10:   LABROW – CHARACTER(1)Input
On entry: indicates the type of labelling to be applied to the rows of the matrix, except in MATLAB mode where LABROW is ignored.
LABROW='N'
Prints no row labels.
LABROW='I'
Prints integer row labels.
LABROW='C'
Prints character labels, which must be supplied in array RLABS.
Constraint: LABROW='N', 'I' or 'C'.
11:   RLABS* – CHARACTER(*) arrayInput
Note: the dimension of the array RLABS must be at least M if LABROW='C', and at least 1 otherwise.
On entry: if LABROW='C', RLABS must contain labels for the rows of the matrix, except in MATLAB mode where RLABS is ignored.
Labels are right-justified when output, in a field which is as wide as necessary to hold the longest row label. Note that this field width is subtracted from the number of usable columns, NCOLS.
12:   LABCOL – CHARACTER(1)Input
On entry: indicates the type of labelling to be applied to the columns of the matrix, except in MATLAB mode where LABCOL is ignored.
LABCOL='N'
Prints no column labels.
LABCOL='I'
Prints integer column labels.
LABCOL='C'
Prints character labels, which must be supplied in array CLABS.
Constraint: LABCOL='N', 'I' or 'C'.
13:   CLABS* – CHARACTER(*) arrayInput
Note: the dimension of the array CLABS must be at least N if LABCOL='C', and at least 1 otherwise.
On entry: if LABCOL='C', CLABS must contain labels for the columns of the matrix, except in MATLAB mode where CLABS is ignored.
Labels are right-justified when output. Any label that is too long for the column width, which is determined by FORM, is truncated.
14:   NCOLS – INTEGERInput
On entry: the maximum output record length. If the number of columns of the matrix is too large to be accommodated in NCOLS characters, the matrix will be printed in parts, containing the largest possible number of matrix columns, and each part separated by a blank line.
NCOLS must be large enough to hold at least one column of the matrix using the format specifier in FORM. If a value less than 0 or greater than 132 is supplied for NCOLS, then the value 80 is used instead.
15:   INDENT – INTEGERInput
On entry: the number of columns by which the matrix (and any title and labels) should be indented. The effective value of NCOLS is reduced by INDENT columns. If a value less than 0 or greater than NCOLS is supplied for INDENT, the value 0 is used instead.
16:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, KL<0.
IFAIL=2
On entry, KU<0.
IFAIL=3
On entry, LDA<KL+KU+1.
IFAIL=4
On entry, USEFRM≠'A', 'B' or 'D'.
IFAIL=5
On entry, the format specifier in FORM is more than 80 characters long.
IFAIL=6
The format specifier in FORM cannot be used to output a number. The specifier probably has too wide a field width or contains an illegal edit descriptor.
IFAIL=7
On entry, either LABROW or LABCOL≠'N', 'I' or 'C'.
IFAIL=8
The quantity NCOLS-INDENT-labwid (where labwid is the width needed for the row labels) is not large enough to hold at least one column of the matrix.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X04DFF is not threaded in any implementation.

9 Further Comments

None.

10 Example

The example program calls X04DFF three times, to print band matrices of different orders and bandwidths; various options for labelling and formatting are illustrated.

10.1 Program Text

Program Text (x04dffe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (x04dffe.r)

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X04EAF : NAG Library, Mark 26

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X04EAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

X04EAF is an easy-to-use routine to print an integer matrix stored in a two-dimensional array.

2 Specification

SUBROUTINE X04EAF ( MATRIX, DIAG, M, N, A, LDA, TITLE, IFAIL)
INTEGER | M, N, A(LDA,*), LDA, IFAIL
CHARACTER(*) | TITLE
CHARACTER(1) | MATRIX, DIAG

3 Description

X04EAF prints an integer matrix. It is an easy-to-use driver for X04EBF. The routine uses default values for the format in which numbers are printed, for labelling the rows and columns, and for output record length.
X04EAF will choose a format code such that numbers will be printed with the smallest I edit descriptor that is large enough to hold all the numbers to be printed.
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 Arguments

1:   MATRIX – CHARACTER(1)Input
On entry: indicates the part of the matrix to be printed.
MATRIX='G'
The whole of the rectangular matrix.
MATRIX='L'
The lower triangle of the matrix, or the lower trapezium if the matrix has more rows than columns.
MATRIX='U'
The upper triangle of the matrix, or the upper trapezium if the matrix has more columns than rows.
Constraint: MATRIX='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.
DIAG='B'
The diagonal elements of the matrix are not referenced and not printed.
DIAG='U'
The diagonal elements of the matrix are not referenced, but are assumed all to be unity, and are printed as such.
DIAG='N'
The diagonal elements of the matrix are referenced and printed.
If MATRIX='G', then DIAG need not be set.
Constraint: if MATRIX≠'G', DIAG='B', 'U' or 'N'.
3:   M – INTEGERInput
4:   N – INTEGERInput
On entry: the number of rows and columns of the matrix, respectively, to be printed.
If either M or N is less than 1, X04EAF will exit immediately after printing TITLE; no row or column labels are printed.
5:   A LDA* – INTEGER arrayInput
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 arguments MATRIX and DIAG, need be set.
6:   LDA – INTEGERInput
On entry: the first dimension of the array A as declared in the (sub)program from which X04EAF is called.
Constraint: LDA≥max 1,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 – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
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.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X04EAF is not threaded in any implementation.

9 Further Comments

A call to X04EAF is equivalent to a call to X04EBF with the following argument values:

NCOLS = 80
INDENT = 0
LABROW = 'I'
LABCOL = 'I'
FORM = ' '

10 Example

This example calls X04EAF twice, first to print a 3 by 5 rectangular matrix, and then to print a 5 by 5 triangular matrix.

10.1 Program Text

Program Text (x04eafe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (x04eafe.r)

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X04EBF : NAG Library, Mark 26

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X04EBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

X04EBF prints an integer matrix stored in a two-dimensional array.

2 Specification

SUBROUTINE X04EBF ( MATRIX, DIAG, M, N, A, LDA, FORM, TITLE, LABROW, RLABS, LABCOL, CLABS, NCOLS, INDENT, IFAIL)
INTEGER | M, N, A(LDA,*), LDA, NCOLS, INDENT, IFAIL
CHARACTER(*) | FORM, TITLE, RLABS(*), CLABS(*)
CHARACTER(1) | MATRIX, DIAG, LABROW, LABCOL

3 Description

X04EBF prints an integer matrix, or part of it, using a format specifier supplied by you. The matrix is output to the unit defined by X04ABF.

4 References

None.

5 Arguments

1:   MATRIX – CHARACTER(1)Input
On entry: indicates the part of the matrix to be printed.
MATRIX='G'
The whole of the rectangular matrix.
MATRIX='L'
The lower triangle of the matrix, or the lower trapezium if the matrix has more rows than columns.
MATRIX='U'
The upper triangle of the matrix, or the upper trapezium if the matrix has more columns than rows.
Constraint: MATRIX='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.
DIAG='B'
The diagonal elements of the matrix are not referenced and not printed.
DIAG='U'
The diagonal elements of the matrix are not referenced, but are assumed all to be unity, and are printed as such.
DIAG='N'
The diagonal elements of the matrix are referenced and printed.
If MATRIX='G', then DIAG need not be set.
Constraint: if MATRIX≠'G', DIAG='B', 'U' or 'N'.
3:   M – INTEGERInput
4:   N – INTEGERInput
On entry: the number of rows and columns of the matrix, respectively, to be printed.
If either M or N is less than 1, X04EBF will exit immediately after printing TITLE; no row or column labels are printed.
5:   A LDA* – INTEGER arrayInput
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 arguments MATRIX and DIAG, need be set.
6:   LDA – INTEGERInput
On entry: the first dimension of the array A as declared in the (sub)program from which X04EBF is called.
Constraint: LDA≥max 1,M.
7:   FORM – CHARACTER(*)Input
On entry: a valid Fortran format code. This may be any format code allowed on the system, whether it is standard Fortran or not. FORM is used to print elements of the matrix A. It may or may not be enclosed in brackets. Examples of valid values for FORM are 'I6', 'I4,2X'.
In addition, there is a special code which forces X04EBF to choose its own format code:
FORM=' '
X04EBF will choose a format code such that numbers will be printed using the smallest edit descriptor that is large enough to hold all the numbers to be printed.
FORM='MATLAB' followed by any of the above, e.g., FORM='MATLABI6', FORM='MATLAB*'
X04EBF will print the matrix such that it can be input into MATLAB. Elements of the matrix will be printed with format specified by the format code following ‘MATLAB’. TITLE will be used as the name of the matrix.
Constraint: the character length of the format specifier in FORM must be ≤80.
8:   TITLE – CHARACTER(*)Input
On entry: a title to be printed above the matrix, or name of the matrix.
If TITLE=' ', no title (and no blank line) will be printed.
If TITLE contains more than NCOLS characters, the contents of TITLE will be wrapped onto more than one line, with the break after NCOLS characters.
Any trailing blank characters in TITLE are ignored.
If printing in MATLAB mode, TITLE will be used as the name of the matrix.
9:   LABROW – CHARACTER(1)Input
On entry: indicates the type of labelling to be applied to the rows of the matrix, except in MATLAB mode where LABROW is ignored.
LABROW='N'
Prints no row labels.
LABROW='I'
Prints integer row labels.
LABROW='C'
Prints character labels, which must be supplied in array RLABS.
Constraint: LABROW='N', 'I' or 'C'.
10:   RLABS* – CHARACTER(*) arrayInput
Note: the dimension of the array RLABS must be at least M if LABROW='C', and at least 1 otherwise.
On entry: if LABROW='C', RLABS must contain labels for the rows of the matrix, except in MATLAB mode where RLABS is ignored.
Labels are right-justified when output, in a field which is as wide as necessary to hold the longest row label. Note that this field width is subtracted from the number of usable columns, NCOLS.
11:   LABCOL – CHARACTER(1)Input
On entry: indicates the type of labelling to be applied to the columns of the matrix, except in MATLAB mode where LABCOL is ignored.
LABCOL='N'
Prints no column labels.
LABCOL='I'
Prints integer column labels.
LABCOL='C'
Prints character labels, which must be supplied in array CLABS.
Constraint: LABCOL='N', 'I' or 'C'.
12:   CLABS* – CHARACTER(*) arrayInput
Note: the dimension of the array CLABS must be at least N if LABCOL='C', and at least 1 otherwise.
On entry: if LABCOL='C', CLABS must contain labels for the columns of the matrix, except in MATLAB mode where CLABS is ignored.
Labels are right-justified when output. Any label that is too long for the column width, which is determined by FORM, is truncated.
13:   NCOLS – INTEGERInput
On entry: the maximum output record length. If the number of columns of the matrix is too large to be accommodated in NCOLS characters, the matrix will be printed in parts, containing the largest possible number of matrix columns, and each part separated by a blank line.
NCOLS must be large enough to hold at least one column of the matrix using the format specifier in FORM. If a value less than 0 or greater than 132 is supplied for NCOLS, then the value 80 is used instead.
14:   INDENT – INTEGERInput
On entry: the number of columns by which the matrix (and any title and labels) should be indented. The effective value of NCOLS is reduced by INDENT columns. If a value less than 0 or greater than NCOLS is supplied for INDENT, the value 0 is used instead.
15:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
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, M>LDA.
IFAIL=4
On entry, the format specifier in FORM is more than 80 characters long.
IFAIL=5
The format specifier in FORM cannot be used to output a number. The specifier probably has too wide a field width or contains an illegal edit descriptor.
IFAIL=6
On entry, either LABROW or LABCOL≠'N', 'I' or 'C'.
IFAIL=7
The quantity NCOLS-INDENT-labwid (where labwid is the width needed for the row labels) is not large enough to hold at least one column of the matrix.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X04EBF is not threaded in any implementation.

9 Further Comments

X04EBF may be used to print a vector, either as a row or as a column. The following code fragment illustrates possible calls.
      INTEGER A(4)
      CHARACTER*1 RLABS(1), CLABS(1)
!     Print vector A as a column vector.
      LDA = 4
      IFAIL = 0
      CALL X04EBF('G','X',1,4,A,LDA,' ',' ','I',RLABS, &
                  'N',CLABS,80,0,IFAIL)
!     Print vector A as a row vector.
      LDA = 1
      IFAIL = 0
        CALL X04EBF('G','X',4,1,A,LDA,' ',' ','N',RLABS, &
                  'I',CLABS,80,0,IFAIL)

10 Example

This example calls X04EBF twice, first to print a 3 by 5 rectangular matrix, and next to print a 5 by 5 upper triangular matrix; various options for labelling and formatting are illustrated.

10.1 Program Text

Program Text (x04ebfe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (x04ebfe.r)

X04 Chapter Contents
X04 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X04 Chapter Introduction : NAG Library, Mark 26

X04 Chapter Contents

NAG Library Chapter Introduction

X04 – Input/Output Utilities

▸▿ Contents

1 Scope of the Chapter
▸▿ 2 Background to the Problems
2.1 Output from NAG Library Routines
2.2 Matrix Printing Routines
3 Recommendations on Choice and Use of Available Routines
4 Functionality Index
5 Auxiliary Routines Associated with Library Routine Arguments
6 Routines Withdrawn or Scheduled for Withdrawal

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 Library Routines

Output from NAG 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 nonzero 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 for your implementation); they may be changed by users. Output of error messages may be controlled by the setting of IFAIL (see Section 3.4.2 in How to Use the NAG Library and its Documentation). Output of advisory messages may usually be controlled by the setting of some other argument (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.
At present only formatted records are output from the Library. All formatted output to an external file from within the Library is performed by X04BAF. Similarly, all formatted input from an external file is performed by X04BBF.
When the library is being called from another language, such as C or Visual Basic, the routines X04ACF and X04ADF may be especially useful: X04ACF connects a file to a FORTRAN unit; X04ADF disconnects a file from a FORTRAN unit.

2.2 Matrix Printing Routines

Routines are provided to allow formatted output of
(a) | general matrices stored in a two-dimensional array (real, complex and integer data types);
(b) | triangular matrices stored in a packed one-dimensional array (real and complex data types);
(c) | band matrices stored in a packed two-dimensional array (real and complex data types).
Routines in (b) and (c) allow printing of matrices stored in formats used in particular by Chapters F06 and F07 of the Library.
By appropriate choice of arguments you can specify titles, labels, maximum output record length, and the format of individual matrix elements. All output is directed to the advisory messages unit, which may be altered by a call to X04ABF.

3 Recommendations on Choice and Use of Available 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 error message unit (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 advisory message unit may be changed to a new value NADV by the statement
CALL X04ABF(1,NADV)
Note that both X04AAF and X04ABF use a Fortran SAVE statement to retain the value of the unit number and so neither routine is safe to use in a multithreaded environment.

4 Functionality Index

Accessing external formatted file,
reading a record X04BBF
writing a record X04BAF
Accessing unit number,
of advisory message unit X04ABF
of error message unit X04AAF
Connecting an external file X04ACF
Disconnecting an external file X04ADF
Printing matrices,
comprehensive routines,
general complex matrix X04DBF
general integer matrix X04EBF
general real matrix X04CBF
packed complex band matrix X04DFF
packed complex triangular matrix X04DDF
packed real band matrix X04CFF
packed real triangular matrix X04CDF
easy-to-use routines,
general complex matrix X04DAF
general integer matrix X04EAF
general real matrix X04CAF
packed complex band matrix X04DEF
packed complex triangular matrix X04DCF
packed real band matrix X04CEF
packed real triangular matrix X04CCF

5 Auxiliary Routines Associated with Library Routine Arguments

None.

6 Routines Withdrawn or Scheduled for Withdrawal

None.
X04 Chapter Contents
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X05AAF : NAG Library, Mark 26

X05 Chapter Contents
X05 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X05AAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

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 Arguments

1:   ITIME 7 – INTEGER arrayOutput
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. In this case, the value returned will be zero.

8 Parallelism and Performance

X05AAF is not threaded in any implementation.

9 Further Comments

None.

10 Example

This example prints out the vector ITIME after a call to X05AAF.

10.1 Program Text

Program Text (x05aafe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (x05aafe.r)

X05 Chapter Contents
X05 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X05ABF : NAG Library, Mark 26

X05 Chapter Contents
X05 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X05ABF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

X05ABF converts from a seven-integer format time and date, as returned by X05AAF, into a character string, returned via the function name.

2 Specification

FUNCTION X05ABF ( ITIME)
CHARACTER(30) X05ABF
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 '** Illegal date/time **'

4 References

None.

5 Arguments

1:   ITIME 7 – INTEGER arrayInput
On entry: a date and time in the format returned by X05AAF.
ITIME 1
Must contain the year as a positive integer.
ITIME 2
Must contain the month, in the range 1–12.
ITIME 3
Must contain the day, in the range 1 to p, where p=28, 29, 30 or 31, depending on the month and year.
ITIME 4
Must contain the hour, in the range 0–23.
ITIME 5
Must contain the minute, in the range 0–59.
ITIME 6
Must contain the second, in the range 0–59.
ITIME 7
Must contain the millisecond, in the range 0–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 15 October 1582, and in Great Britain since 14 September 1752. Entry to this routine with a date earlier than these will therefore not return a day name that is historically accurate.

8 Parallelism and Performance

X05ABF is not threaded in any implementation.

9 Further Comments

Two dates stored in character string format, as returned by this routine, may be compared by X05ACF.

10 Example

This example initializes a time in ITIME, and converts it to character format by a call to X05ABF.

10.1 Program Text

Program Text (x05abfe.f90)

10.2 Program Data

Program Data (x05abfe.d)

10.3 Program Results

Program Results (x05abfe.r)

X05 Chapter Contents
X05 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X05ACF : NAG Library, Mark 26

X05 Chapter Contents
X05 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X05ACF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

X05ACF compares two date/time character strings, each stored in the format returned by X05ABF.

2 Specification

FUNCTION X05ACF ( CTIME1, CTIME2)
INTEGER X05ACF
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:
  • if X05ACF =-1, the first date/time string is earlier than the second;
  • if X05ACF =0, the two date/time strings are equivalent;
  • if X05ACF =1, the first date/time string is later than the second.

4 References

None.

5 Arguments

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 9 for further details.

6 Error Indicators and Warnings

None.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X05ACF is not threaded in any implementation.

9 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.
Fields in the character string must be separated by one or more spaces.
The case of all alphabetic characters is not significant.
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’

10 Example

This example initializes two date/time strings, and compares them by a call to X05ACF.

10.1 Program Text

Program Text (x05acfe.f90)

10.2 Program Data

Program Data (x05acfe.d)

10.3 Program Results

Program Results (x05acfe.r)

X05 Chapter Contents
X05 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X05BAF : NAG Library, Mark 26

X05 Chapter Contents
X05 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X05BAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

X05BAF returns the amount of processor time used since an unspecified previous time, via the routine name.

2 Specification

FUNCTION X05BAF ( )
REAL (KIND=nag_wp) 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 Arguments

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 Parallelism and Performance

X05BAF is not threaded in any implementation.

9 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.

10 Example

This example makes an initial call to X05BAF. In a loop it performs some computations and makes another call to X05BAF; the difference between the value from this call and the initial is used to track the time taken by those computations. The loop is exited if an allotted time limit is exceeded.

10.1 Program Text

Program Text (x05bafe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (x05bafe.r)

X05 Chapter Contents
X05 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X05 Chapter Contents : NAG Library Manual, Mark 26

X05 Chapter Introduction

NAG Library Chapter Contents

X05 – Date and Time Utilities

X05 Chapter Introduction – a description of the Chapter and an overview of the algorithms available

Routine Name | Mark of Introduction | Purpose
X05AAF Example Text | 14 | nagf_time_date_array Return date and time as an array of integers
X05ABF Example Text Example Data | 14 | nagf_time_date_array_string Convert array of integers representing date and time to character string
X05ACF Example Text Example Data | 14 | nagf_time_date_string_compare Compare two character strings representing date and time
X05BAF Example Text | 14 | nagf_time_cpu Return the CPU time
X05 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X05 Chapter Introduction : NAG Library, Mark 26

X05 Chapter Contents

NAG Library Chapter Introduction

X05 – Date and Time Utilities

▸▿ Contents

1 Scope of the Chapter
▸▿ 2 Background to the Problems
2.1 Real Time
2.2 Processor Time
3 Recommendations on Choice and Use of Available Routines
4 Routines Withdrawn or Scheduled for Withdrawal

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 Available 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.

4 Routines Withdrawn or Scheduled for Withdrawal

None.
X05 Chapter Contents
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X06AAF : NAG Library, Mark 26

X06 Chapter Contents
X06 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X06AAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

X06AAF sets the number of threads requested for subsequent OpenMP parallel regions.

2 Specification

SUBROUTINE X06AAF ( NUM, IFAIL)
INTEGER NUM, IFAIL

3 Description

X06AAF, for multi-threaded implementations, sets the number of threads to be requested for subsequent parallel regions to NUM. The first element of the list held by the OpenMP Internal Control Variable (ICV) used in determining the number of threads is set. See the Users' Note for your implementation for details of the scope of this routine.
The number of threads used in parallel regions will be equal to, or less than, the value of the ICV. The actual number of threads used is dependent on several factors, such as the presence of a num_threads clause on the parallel directive or the number of threads already in use by the program. Please refer to Section 4 for a full description of how the number of threads is chosen for a particular parallel region.
In serial implementations of the NAG Library this routine has no effect. See the X06 Chapter Introduction for a discussion of the behaviour of these routines when called in serial.

4 References

OpenMP Specifications http://openmp.org/wp/OpenMP-Specifications
Chapman B, Jost G and van der Pas R (2008) Using OpenMP Portable Shared Memory Parallel Programming The MIT Press

5 Arguments

1:   NUM – INTEGERInput
On entry: the number of threads requested for subsequent OpenMP parallel regions.
Constraint: NUM≥1.
2:   IFAIL – INTEGERInput/Output
On entry: IFAIL must be set to 0, -1​ or ​1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. When the value -1​ or ​1 is used it is essential to test the value of IFAIL on exit.
On exit: IFAIL=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry IFAIL=0 or -1, explanatory error messages are output on the current error message unit (as defined by X04AAF).
Errors or warnings detected by the routine:
IFAIL=1
On entry, NUM=value.
Constraint: NUM≥1.
IFAIL=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
IFAIL=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X06AAF is not threaded in any implementation.

9 Further Comments

None.

10 Example

In this example we presume a multi-threaded implementation of the NAG Library. We set the OpenMP Internal Control Variable used in determining the number of threads to 5 with a call to X06AAF and retrieve it again with X06ACF.
We then, using X06ABF, display the number of threads in use both outside, and inside, the OpenMP parallel region.
We expect to see X06ABF returning 1 outside of the parallel region, as the current team of threads there will consist of a single thread, and 5 from within it.
If you use a serial implementation of the NAG Library, regardless of whether the code is compiled with OpenMP or not, calling X06AAF has no effect and X06ABF and X06ACF will always return 1. The appropriate results file will be included with the distribution material for your implementation.

10.1 Program Text

Program Text (x06aafe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (x06aafe.r)

X06 Chapter Contents
X06 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X06ABF : NAG Library, Mark 26

X06 Chapter Contents
X06 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X06ABF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

X06ABF returns the number of OpenMP threads in the current team.

2 Specification

FUNCTION X06ABF ( )
INTEGER X06ABF

3 Description

X06ABF, for multi-threaded implementations, returns the number of OpenMP threads in the current team. If the number of threads is deemed critical then you are advised to use X06ABF to retrieve this value as it may be less than that requested with either a call to X06AAF, your OMP_NUM_THREADS environment variable value or by using a num_threads clause on an OpenMP parallel directive.
The number of threads actually in use in a parallel region is dependent on several factors. Please refer to Section 4 for a full description of how the number of threads is chosen for a particular parallel region.
If this routine is called from a sequential part of a multi-threaded program then it will return the value 1.
In serial implementations of the NAG Library this routine will always return 1. See the X06 Chapter Introduction for a discussion of the behaviour of these routines when called in serial.

4 References

OpenMP Specifications http://openmp.org/wp/OpenMP-Specifications
Chapman B, Jost G and van der Pas R (2008) Using OpenMP Portable Shared Memory Parallel Programming The MIT Press

5 Arguments

None.

6 Error Indicators and Warnings

None.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X06ABF is not threaded in any implementation.

9 Further Comments

None.

10 Example

See Section 10 in X06AAF for a demonstration of how to use X06ABF.
X06 Chapter Contents
X06 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X06ACF : NAG Library, Mark 26

X06 Chapter Contents
X06 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X06ACF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

X06ACF returns an upper bound on the number of threads used for subsequent OpenMP parallel regions.

2 Specification

FUNCTION X06ACF ( )
INTEGER X06ACF

3 Description

X06ACF, for multi-threaded implementations, returns the number of the threads to be requested for subsequent parallel regions. The value is the first element of the list held by the OpenMP Internal Control Variable (ICV) used in determining the number of threads. See Users' Note for your implementation for details of the scope of this routine.
The number of threads used in parallel regions will be equal to, or less than, the first value of the ICV. The actual number of threads used is dependent on several factors, such as the presence of a num_threads clause on the parallel directive or the number of threads already in use by the program. Please refer to Section 4 for a full description of how the number of threads is chosen for a particular parallel region.
In serial implementations of the NAG Library this routine will always return 1. See the X06 Chapter Introduction for a discussion of the behaviour of these routines when called in serial.

4 References

OpenMP Specifications http://openmp.org/wp/OpenMP-Specifications
Chapman B, Jost G and van der Pas R (2008) Using OpenMP Portable Shared Memory Parallel Programming The MIT Press

5 Arguments

None.

6 Error Indicators and Warnings

None.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X06ACF is not threaded in any implementation.

9 Further Comments

None.

10 Example

See Section 10 in X06AAF for a demonstration of how to use X06ACF.
X06 Chapter Contents
X06 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X06ADF : NAG Library, Mark 26

X06 Chapter Contents
X06 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X06ADF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

X06ADF returns the OpenMP thread number of the calling thread.

2 Specification

FUNCTION X06ADF ( )
INTEGER X06ADF

3 Description

X06ADF, for multi-threaded implementations, returns the calling OpenMP thread's unique thread number within the current team. The master thread will always return 0. The remaining threads will return a value between 1 and the value returned by X06ABF less 1.
If this routine is called from a sequential part of a multi-threaded program then it will return the value 0.
In serial implementations of the NAG Library this routine will always return 0. See the X06 Chapter Introduction for a discussion of the behaviour of these routines when called in serial.

4 References

OpenMP Specifications http://openmp.org/wp/OpenMP-Specifications
Chapman B, Jost G and van der Pas R (2008) Using OpenMP Portable Shared Memory Parallel Programming The MIT Press

5 Arguments

None.

6 Error Indicators and Warnings

None.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X06ADF is not threaded in any implementation.

9 Further Comments

None.

10 Example

In this example we presume a multi-threaded implementation of the NAG Library. We call X06ADF both outside and inside an OpenMP active parallel region. Outside we expect a single thread to display the value 0. Inside the region we use the value to have only the master thread display the result.
We also call X06AFF inside and outside of the region. Outside we expect it to return 0, as we are not in an active parallel region, and inside we expect to see the value 1, indicating that the parallel region is an active one.
If you use a serial implementation of the NAG library, regardless of whether the code is compiled with OpenMP or not, X06ABF will always return 1 and X06ADF and X06AFF will always return 0. The appropriate results file will be included with the distribution material for your implementation.

10.1 Program Text

Program Text (x06adfe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (x06adfe.r)

X06 Chapter Contents
X06 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X06AFF : NAG Library, Mark 26

X06 Chapter Contents
X06 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X06AFF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

X06AFF returns 1 if called from within an active OpenMP parallel region, and 0 otherwise.

2 Specification

FUNCTION X06AFF ( )
INTEGER X06AFF

3 Description

X06AFF, for multi-threaded implementations, returns 1 if called from within an active OpenMP parallel region, and 0 otherwise.
Note that the equivalent OpenMP routine omp_in_parallel() returns a logical value.
In serial implementations of the NAG Library this routine will always return 0. See the X06 Chapter Introduction for a discussion of the behaviour of these routines when called in serial.

4 References

OpenMP Specifications http://openmp.org/wp/OpenMP-Specifications
Chapman B, Jost G and van der Pas R (2008) Using OpenMP Portable Shared Memory Parallel Programming The MIT Press

5 Arguments

None.

6 Error Indicators and Warnings

None.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X06AFF is not threaded in any implementation.

9 Further Comments

None.

10 Example

See Section 10 in X06ADF for a demonstration of how to use X06AFF.
X06 Chapter Contents
X06 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X06AGF : NAG Library, Mark 26

X06 Chapter Contents
X06 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X06AGF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

X06AGF enables or disables nested OpenMP parallelism.

2 Specification

SUBROUTINE X06AGF ( NESTING)
INTEGER NESTING

3 Description

X06AGF, for multi-threaded implementations, enables or disables the nesting of OpenMP parallel regions by setting an OpenMP Internal Control Variable (ICV) and any vendor library specific options where that is possible. See the Users' Note for your implementation for details of the scope of X06AGF.
Nesting is disabled by default in OpenMP.
In serial implementations of the NAG Library X06AGF has no effect. See the Chapter X06 for a discussion of the behaviour of these routines when called in serial.

4 References

OpenMP Specifications http://openmp.org/wp/OpenMP-Specifications
Chapman B, Jost G and van der Pas R (2008) Using OpenMP Portable Shared Memory Parallel Programming The MIT Press

5 Arguments

1:   NESTING – INTEGERInput
On entry: if NESTING=0, nesting of OpenMP parallel regions is disabled, otherwise it is enabled.

6 Error Indicators and Warnings

None.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X06AGF is not threaded in any implementation.

9 Further Comments

None.

10 Example

In this example we presume a multi-threaded implementation of the NAG Library. We call X06AGF to enable the nesting of OpenMP parallel regions by setting an ICV. Inside a first, or ‘outer’, parallel region we call X06AHF to display the status of nesting, and expect to see it return the value 1.
Each thread then spawns a second ‘inner’ parallel region. Within this region we have each thread increment the value total. As there are 5 threads in the outer region and 3 threads in each inner region we expect the final value of this variable to be 15.
If you use a serial implementation of the NAG library, regardless of whether the code is compiled with OpenMP or not, X06AGF will have no effect and X06AHF will always return 0. The total number of threads will be 1. The appropriate results file will be included with the distribution material for your implementation.

10.1 Program Text

Program Text (x06agfe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (x06agfe.r)

X06 Chapter Contents
X06 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X06AHF : NAG Library, Mark 26

X06 Chapter Contents
X06 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X06AHF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

X06AHF returns 1 if nested OpenMP parallelism has been enabled, and 0 otherwise.

2 Specification

FUNCTION X06AHF ( )
INTEGER X06AHF

3 Description

X06AHF, for multi-threaded implementations, tests whether the nesting of OpenMP parallel regions has been enabled as if with a call to X06AGF. The return value will be 1 if nesting is enabled or 0 if it is disabled.
Note the equivalent OpenMP routine omp_get_nested() returns a logical value.
In serial implementations of the NAG Library X06AHF will always return 0. See the X06 Chapter Introduction for a discussion of the behaviour of these routines when called in serial.

4 References

OpenMP Specifications http://openmp.org/wp/OpenMP-Specifications
Chapman B, Jost G and van der Pas R (2008) Using OpenMP Portable Shared Memory Parallel Programming The MIT Press

5 Arguments

None.

6 Error Indicators and Warnings

None.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X06AHF is not threaded in any implementation.

9 Further Comments

None.

10 Example

See Section 10 in X06AGF for a demonstration of how to use X06AHF.
X06 Chapter Contents
X06 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X06 Chapter Contents : NAG Library Manual, Mark 26

X06 Chapter Introduction

NAG Library Chapter Contents

X06 – OpenMP Utilities

X06 Chapter Introduction – a description of the Chapter and an overview of the algorithms available

Routine Name | Mark of Introduction | Purpose
X06AAF Example Text | 25 | nagf_omp_set_num_threads Sets the number of threads for OpenMP parallel regions
X06ABF | 25 | nagf_omp_get_num_threads The number of OpenMP threads in the current team
X06ACF | 25 | nagf_omp_get_max_threads An upper bound on the number of threads in the next parallel region
X06ADF Example Text | 25 | nagf_omp_get_thread_num The OpenMP thread number of the calling thread
X06AFF | 25 | nagf_omp_in_parallel Tests for an active OpenMP parallel region
X06AGF Example Text | 25 | nagf_omp_set_nested Enables or disables nested OpenMP parallelism
X06AHF | 25 | nagf_omp_get_nested Tests the status of nested OpenMP parallelism
X06XAF | 26 | nagf_using_threaded_impl Tests whether a threaded NAG Library is being used
X06 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X06 Chapter Introduction : NAG Library, Mark 26

X06 Chapter Contents

NAG Library Chapter Introduction

X06 – OpenMP Utilities

▸▿ Contents

1 Scope of the Chapter
2 Background to the Problems
▸▿ 3 Recommendations on Choice and Use of Available Routines
3.1 Multi-threaded Implementations of the NAG Library
3.2 Serial Implementations of the NAG Library
4 Functionality Index
5 Auxiliary Routines Associated with Library Routine Arguments
6 Routines Withdrawn or Scheduled for Withdrawal

1 Scope of the Chapter

This chapter contains utilities for controlling the OpenMP environment for your program. They are based on OpenMP runtime library routines, although their functionality varies slightly.

2 Background to the Problems

These routines have been designed to be used with multi-threaded implementations of the NAG Library. In these implementations, these routines enable you to change and interrogate the OpenMP threading environment for your whole program. In describing their use we assume you have followed the recommendations in the Users' Note. Routines are provided to control the number of threads, test whether you have active threads, get a thread's unique thread number and enable and disable nested parallelism. Readers are directed to How to Use the NAG Library and its Documentation for a wider discussion on parallelism.
As these routines apply to the whole program they will affect the OpenMP in your calling program, OpenMP used internally in the NAG Library and also multi-threading in any underlying vendor libraries, where provided. See the Users' Note of your implementation for information on what underlying libraries have been used and for the scope of the X06 routines.
OpenMP uses the notion of Internal Control Variables (ICVs) to control the behaviour of a multi-threaded program. There are only two that are relevant to this chapter. One is used in determining the number of threads and the other controls the nesting of parallel regions. The user does not have direct access to ICVs, but they can be changed or reported with a call to an X06 routine.

3 Recommendations on Choice and Use of Available Routines

The routine X06XAF can be used to determine, at runtime, whether you are using a multi-threaded implementation of the NAG Library or not.

3.1 Multi-threaded Implementations of the NAG Library

If you are not using OpenMP in your program we recommend you set the number of threads with the OMP_NUM_THREADS environment variable as described in the Users' Note. This is the number of threads that will then be used in multi-threaded NAG Library routines. The ICV is set from this environment variable but the value can be changed with a call to X06AAF. It applies to the next parallel region, whether that is your own, one encountered by a NAG routine or an underlying vendor library routine.
Whilst the ICV strongly influences the number of threads used, the design of OpenMP is such that it does not dictate it. Many factors affect the number of threads in a particular parallel region including, but not restricted to, the presence of a num_threads clause and the number of threads already in use by a program. However, in most cases the number of threads requested will be used. The value of the ICV is retrieved with a call to X06ACF. The return value is an upper bound on the number of threads. If it is crucial to know the number of threads that are actually in use for a particular parallel region we recommend you get this number with a call to X06ABF, once you are inside the parallel region.
OpenMP threads have a unique thread number, which can be retrieved for a particular thread by a call to X06ADF. The master thread is always numbered 0.
To check whether you are in an active parallel region, where there is more than one thread, X06AFF can be used.
The routines X06ABF, X06ADF and X06AFF are only relevant when called from within an OpenMP parallel region. This could be one of your own or one in a NAG routine. The cases where these routines apply to NAG routines are the ones which take a user-supplied function. There are routines in Chapters D01, D03, E05 and F01 which contain parallel regions that have calls to user-supplied functions from within them. You may, for example, wish to know the thread number, the number of threads or simply check whether this NAG parallel region is an active one in your supplied function.
Nested parallelism is where a parallel region is contained within another. That is, each thread in the outer region spawns its own inner parallel region of which it is the master thread. X06AGF can be used to enable nested parallelism by setting the nesting ICV. X06AHF can be used to retrieve the value of this ICV. Nesting will be disabled by default and you should have a good reason for using nested parallel regions with careful thought given to the hardware resources you have.
If you wish to call a NAG multi-threaded routine and have it execute in parallel from each thread in your own parallel region you will need to enable nested parallelism. If you do not enable it the NAG routine will simply execute in serial. When using nesting the environment variable OMP_NUM_THREADS can be given a comma-separated list of integers representing the number of threads you wish to use at each level of parallelism. Recall that X06AAF can be used to set the number of threads for the next parallel region. To change the number of threads for a NAG routine in this scenario, you would call X06AAF once inside your own parallel region.

3.2 Serial Implementations of the NAG Library

When using a serial implementation of the NAG Library the X06 routines return a value in line with your whole program being executed in serial. This is irrespective of what OMP_NUM_THREADS has been set to or if you have compiled your program with OpenMP.
Table 1 shows the behaviour of these routines in serial implementations of the NAG Library.
Note that underlying vendor libraries may still be using multi-threading. Check the Users' Note document of your implementation.
If you are using OpenMP in your code together with a serial implementation of the NAG Library, we recommend you use the OpenMP runtime library routines directly to control threading in your program.
Routine | Behaviour when called from a serial implementation of the NAG Library
X06AAF | No effect
X06ABF | Returns 1
X06ACF | Returns 1
X06ADF | Returns 0
X06AFF | Returns 0
X06AGF | No effect
X06AHF | Returns 0

4 Functionality Index

Active parallel region test X06AFF
Nested OpenMP Parallelism
enable or disable X06AGF
get nesting status X06AHF
Number of OpenMP Threads
get upper bound for next parallel region X06ACF
in current team X06ABF
set for next parallel region X06AAF
Threaded library test X06XAF
Thread number X06ADF

5 Auxiliary Routines Associated with Library Routine Arguments

None.

6 Routines Withdrawn or Scheduled for Withdrawal

None.
X06 Chapter Contents
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X06XAF : NAG Library, Mark 26

X06 Chapter Contents
X06 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X06XAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

X06XAF returns 1 when using a multi-threaded implementation of the NAG Library and 0 otherwise.

2 Specification

FUNCTION X06XAF ( )
INTEGER X06XAF

3 Description

X06XAF can be used to determine whether you are using a serial or multi-threaded implementation of the NAG Library. In particular, with this information the behaviour of the other routines in this chapter can be predicted, as described in the X06 Chapter Introduction.
The routine returns 1 when a multi-threaded implementation of the Library is being used and 0 if a serial implementation is being used.

4 References

None.

5 Arguments

None.

6 Error Indicators and Warnings

None.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X06XAF is not threaded in any implementation.

9 Further Comments

None.

10 Example

None.
X06 Chapter Contents
X06 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X07AAF : NAG Library, Mark 26

X07 Chapter Contents
X07 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X07AAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
▸▿ 10 Example
10.1 Program Text
10.2 Program Data
10.3 Program Results

1 Purpose

X07AAF determines whether a floating-point number is finite.

2 Specification

FUNCTION X07AAF ( X)
LOGICAL X07AAF
REAL (KIND=nag_wp) X

3 Description

X07AAF returns .TRUE. if and only if X is finite, and returns .FALSE. otherwise.

4 References

IEEE (2008) Standard for Floating-Point Arithmetic IEEE Standard 754-2008 IEEE, New York.

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the number whose status is to be determined.

6 Error Indicators and Warnings

None.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X07AAF is not threaded in any implementation.

9 Further Comments

This routine will return .FALSE. if the argument X is either infinite or a NaN (Not A Number).

10 Example

This program creates various infinities, NaNs and normal numbers and distinguishes between them.

10.1 Program Text

Program Text (x07aafe.f90)

10.2 Program Data

None.

10.3 Program Results

Program Results (x07aafe.r)

X07 Chapter Contents
X07 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X07ABF : NAG Library, Mark 26

X07 Chapter Contents
X07 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X07ABF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

X07ABF determines whether a floating-point number is a NaN (Not A Number).

2 Specification

FUNCTION X07ABF ( X)
LOGICAL X07ABF
REAL (KIND=nag_wp) X

3 Description

X07ABF returns .TRUE. if and only if X is a NaN, and returns .FALSE. otherwise.

4 References

IEEE (2008) Standard for Floating-Point Arithmetic IEEE Standard 754-2008 IEEE, New York.

5 Arguments

1:   X – REAL (KIND=nag_wp)Input
On entry: the number whose status is to be determined.

6 Error Indicators and Warnings

None.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X07ABF is not threaded in any implementation.

9 Further Comments

None.

10 Example

See Section 10 in X07AAF.
X07 Chapter Contents
X07 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X07BAF : NAG Library, Mark 26

X07 Chapter Contents
X07 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X07BAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

X07BAF creates a signed infinite value.

2 Specification

SUBROUTINE X07BAF ( ISIGN, X)
INTEGER | ISIGN
REAL (KIND=nag_wp) | X

3 Description

X07BAF sets X to be positive or negative infinity.

4 References

IEEE (2008) Standard for Floating-Point Arithmetic IEEE Standard 754-2008 IEEE, New York.

5 Arguments

1:   ISIGN – INTEGERInput
On entry: determines the sign of the infinity to be created.
If ISIGN is greater than or equal to 0, a positive infinity is returned, otherwise a negative infinity is returned.
2:   X – REAL (KIND=nag_wp)Output
On exit: the required infinite value.

6 Error Indicators and Warnings

None.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X07BAF is not threaded in any implementation.

9 Further Comments

None.

10 Example

See Section 10 in X07AAF.
X07 Chapter Contents
X07 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X07BBF : NAG Library, Mark 26

X07 Chapter Contents
X07 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X07BBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

X07BBF creates a NaN (Not A Number).

2 Specification

SUBROUTINE X07BBF ( QUIET, X)
INTEGER | QUIET
REAL (KIND=nag_wp) | X

3 Description

X07BBF sets X to be a quiet or a signalling NaN (Not A Number).

4 References

IEEE (2008) Standard for Floating-Point Arithmetic IEEE Standard 754-2008 IEEE, New York.

5 Arguments

1:   QUIET – INTEGERInput
On entry: determines whether a quiet or a signalling NaN is to be created. If QUIET=1, the returned NaN is quiet, otherwise it is signalling. See reference IEEE (2008) for the distinction between the two kinds.
2:   X – REAL (KIND=nag_wp)Output
On exit: the required NaN value.

6 Error Indicators and Warnings

None.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X07BBF is not threaded in any implementation.

9 Further Comments

None.

10 Example

See Section 10 in X07AAF.
X07 Chapter Contents
X07 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X07CAF : NAG Library, Mark 26

X07 Chapter Contents
X07 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X07CAF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

X07CAF gets the current IEEE exception halting mode.

2 Specification

SUBROUTINE X07CAF ( EXCEPTIONMODE)
INTEGER EXCEPTIONMODE(3)

3 Description

X07CAF gets the current IEEE exception halting mode for the three common exceptions: overflow, divide-by-zero and invalid operation.

4 References

IEEE (2008) Standard for Floating-Point Arithmetic IEEE Standard 754-2008 IEEE, New York.

5 Arguments

1:   EXCEPTIONMODE 3 – INTEGER arrayOutput
On exit: each of the three elements of EXCEPTIONMODE is set to 1 if the corresponding condition will raise an exception, and is set to 0 otherwise. EXCEPTIONMODE 1 concerns floating-point overflow, EXCEPTIONMODE 2 concerns floating-point division by zero, and EXCEPTIONMODE 3 concerns floating-point invalid operation.

6 Error Indicators and Warnings

None.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X07CAF is not threaded in any implementation.

9 Further Comments

None.

10 Example

See Section 10 in X07AAF.
X07 Chapter Contents
X07 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X07CBF : NAG Library, Mark 26

X07 Chapter Contents
X07 Chapter Introduction
NAG Library Manual

NAG Library Routine Document

X07CBF

Note: before using this routine, please read the Users' Note for your implementation to check the interpretation of bold italicised terms and other implementation-dependent details.

▸▿ Contents

1 Purpose
2 Specification
3 Description
4 References
5 Arguments
6 Error Indicators and Warnings
7 Accuracy
8 Parallelism and Performance
9 Further Comments
10 Example

1 Purpose

X07CBF sets the current IEEE exception halting mode.

2 Specification

SUBROUTINE X07CBF ( EXCEPTIONMODE)
INTEGER EXCEPTIONMODE(3)

3 Description

X07CBF sets the current IEEE exception halting mode for the three common exceptions: overflow, divide-by-zero and invalid operation.

4 References

IEEE (2008) Standard for Floating-Point Arithmetic IEEE Standard 754-2008 IEEE, New York.

5 Arguments

1:   EXCEPTIONMODE 3 – INTEGER arrayInput
On entry: each of the three elements of EXCEPTIONMODE must contain any nonzero value if the corresponding condition should raise an exception, and contain 0 otherwise. EXCEPTIONMODE 1 concerns floating-point overflow, EXCEPTIONMODE 2 concerns floating-point division by zero, and EXCEPTIONMODE 3 concerns floating-point invalid operation.

6 Error Indicators and Warnings

None.

7 Accuracy

Not applicable.

8 Parallelism and Performance

X07CBF is not threaded in any implementation.

9 Further Comments

None.

10 Example

See Section 10 in X07AAF.
X07 Chapter Contents
X07 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X07 Chapter Contents : NAG Library Manual, Mark 26

X07 Chapter Introduction

NAG Library Chapter Contents

X07 – IEEE Arithmetic

X07 Chapter Introduction – a description of the Chapter and an overview of the algorithms available

Routine Name | Mark of Introduction | Purpose
X07AAF Example Text | 24 | nagf_is_finite Determines whether its argument has a finite value
X07ABF | 24 | nagf_is_nan Determines whether its argument is a NaN (Not A Number)
X07BAF | 24 | nagf_create_infinity Creates a signed infinite value.
X07BBF | 24 | nagf_create_nan Creates a NaN (Not A Number)
X07CAF | 24 | nagf_get_ieee_exception_mode Gets current behaviour of floating-point exceptions
X07CBF | 24 | nagf_set_ieee_exception_mode Sets behaviour of floating-point exceptions
X07 Chapter Introduction
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


X07 Chapter Introduction : NAG Library, Mark 26

X07 Chapter Contents

NAG Library Chapter Introduction

X07 – IEEE Arithmetic

▸▿ Contents

1 Scope of the Chapter
2 Background to the Problems
3 Recommendations on Choice and Use of Available Routines
4 Functionality Index
5 Auxiliary Routines Associated with Library Routine Arguments
6 Routines Withdrawn or Scheduled for Withdrawal

1 Scope of the Chapter

This chapter provides routines to handle various aspects of IEEE floating-point arithmetic behaviour.

2 Background to the Problems

Modern systems allow you to control what happens to your program when an exceptional event such as overflow or division by zero occurs. Often, the default behaviour is for program execution to continue, while setting an appropriate flag. Sometimes the default behaviour is to halt execution and print a warning or error message.
The routines in Chapter X07 allow creation and detection of NaNs (Not a Number) and infinities, as well as alteration of the behaviour of a program when an exception occurs.

3 Recommendations on Choice and Use of Available Routines

Routines are provided to detect and create IEEE NaN (Not a Number) and infinity values, and to get and set the halting mode of various floating-point exceptions.

4 Functionality Index

Create a floating-point infinity X07BAF
Create a floating-point NaN (Not a Number) X07BBF
Determine whether a floating-point number is finite X07AAF
Determine whether a floating-point number is NaN (Not a Number) X07ABF
Get current behaviour of floating-point exceptions X07CAF
Set behaviour of floating-point exceptions X07CBF

5 Auxiliary Routines Associated with Library Routine Arguments

None.

6 Routines Withdrawn or Scheduled for Withdrawal

None.
X07 Chapter Contents
NAG Library Manual
© The Numerical Algorithms Group Ltd, Oxford, UK. 2016


Next Break point

Selecting [Run | Next Break point] moves the cursor to the beginning of the next line in the file that has a break point set. If no break point is set later in the file, the cursor position is unchanged.

Related Items

Break point
Previous Break point


Previous Break point

Selecting [Run | Previous Break point] moves the cursor to the beginning of the last preceding line in the file that has a break point set. If no break point is set on any preceding line, the cursor position is unchanged.

Related Items

Break point
Next Break point