NAG Library Manual, Mark 26
NAG AD Library Manual, Mark 26
NAG C Library Manual, Mark 26

NAG Library

NAG Fortran Library News, Mark 26

NAG Library Manual, Mark 26
NAG AD Library Manual, Mark 26
NAG C Library Manual, Mark 26

▸▿ Contents

© The Numerical Algorithms Group Ltd. 2018

1
Introduction

At Mark 26, the NAG Library now contains 1889 user-callable routines, all of which are documented, of which 71 are new.
In collaboration with the group Informatik 12: Software and Tools for Computational Engineering from RWTH Aachen University, the Library now includes the initial version of the NAG AD Library. Supplementary documentation is provided for the NAG AD Library, including: the NAG AD Library Introduction, Chapter X10, and 19 user-callable routine documents listed in the NAG AD Library Contents.
In addition to the new NAG AD Library, the following summarises additional content and changes to the NAG Library.
Chapter C05 (Roots of One or More Transcendental Equations) has a new routine that finds a solution of a system of nonlinear equations using Anderson acceleration.
Chapter C06 (Summation of Series) has a new routine that calculates the fast Gauss transform approximation to the discrete Gauss transform.
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, the 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.
The NAG Modelling Optimization Suite also contains two new solvers – the first is a derivative free solver for nonlinear least squares subject to bound constraints, aimed at small to medium sized data fitting or calibration problems (~100 variables) and is particularly suitable when the objective function is noisy or expensive to evaluate. The second is a new interior point method for large scale linear programming problems (LP) that should offer significant speed-ups compared to the existing LP solvers in the NAG Library.
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 a new nearest correlation routine that, using a shrinking method, allows the fixing of arbitrary elements in the input matrix.
Chapter G04 (Analysis of Variance) has a new routine for calculating the intraclass correlation (ICC) for a number of different rater reliability study designs.
Chapter S (Approximations of Special Functions) contains a new set of routines to evaluate Struve functions H0, H1, L0 and L1.
Chapter X06 (OpenMP Utilities) has a new routine to identify, at runtime, whether you are using a threaded Library or not.
Chapter X10 (Automatic Differentiation Utilities) is a new chapter introduced to provide utility operations used in conjunction with the NAG AD Library.
At Mark 26 we have made a number of changes to the documentation and long names as follows.
The specification of routines in routine documents (see for example Section 2 in d03pdf/d03pda) now includes the C Header interface which can be used to call a NAG Library routine from C or C++; the name used for this interface is the Fortran Interface short name appended by an underscore (e.g., d03faf_ corresponds to d03faf). For routines with 'a' and 'f' versions, the same approach also applies to the 'a' version (e.g., d03pda_ corresponds to d03pda).
Some routine long names have been changed for the following reasons:
(a) to differentiate between linear system (Chapter F07) and eigensystem/least squares system (Chapter F08) LAPACK routines.
(b) to consistently use the Chapter identifying word (e.g., ‘opt’ for Chapter E04) as the second word in the long name.
(c) to avoid using a digit as the first character of the third word in the long name. This allows other environments to use the same long name: third and following words are used as a routine identifier inside a class name using the first two words.
(d) the word ‘withdrawn’ has been changed to ‘withdraw’ to be consistent with other routine long names using ‘withdraw’.
(e) ‘withdraw_’ has been removed from a few routines that are no longer to be withdrawn.
A full list of the long names which have changed can be found on the NAG website.
We have also 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.
The How to Use the NAG Library and its Documentation now provides 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 we have 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 and links to all the Fortran, C and AD Library Manuals. PDF is no longer provided, but most browsers provide a print-to-PDF feature.

2
New Routines

2.1
New Routines at Mark 26.2

The NAG Library at Mark 26.2 includes the first release of the NAG AD Library. See the NAG AD Library Contents.

2.2
New Routines at Mark 26.1

The 20 new user-callable routines included in the NAG Library at Mark 26.1 are as follows.
Routine
Name
Purpose
c05mdfSolution of a system of nonlinear equations using Anderson acceleration (reverse communication)
c06safMultidimensional fast Gauss transform
e04fffDerivative-free (DFO) solver for a nonlinear least squares objective function with bounded variables
e04mtfLinear programming (LP), sparse, interior point method (IPM)
e04rmfDefine a nonlinear least squares objective function to a problem initialized by e04raf
e04rxfRetrieve or write a piece of information in a problem handle initialized by e04raf
g04gafIntraclass correlation (ICC) for assessing rater reliability
g22yafSpecify a linear model via a formula string
g22ybfDescribe a dataset
g22ycfConstruct a design matrix from a linear model specified using g22yaf
g22ydfConstruct a vector indicating which columns of a design matrix to include in a submodel specified using g22yaf
g22zafDestroy a G22 handle and deallocate all the memory used
g22zmfOption setting routine for Chapter G22
g22znfOption getting routine for Chapter G22
s17gafStruve function of order 0, H0x
s17gbfStruve function of order 1, H1x
s18gafModified Struve function of order 0, L0x
s18gbfModified Struve function of order 1, L1x
s18gcfThe function I0x-L0x, where I0x is a modified Bessel function and L0x is a Struve function
s18gdfThe function I1x-L1x, where I1x is a modified Bessel function and L1x is a Struve function

2.3
New Routines at Mark 26.0

The 37 new user-callable routines included in the NAG Library at Mark 26.0 are as follows.
Routine
Name
Purpose
d01tdfCalculation of weights and abscissae for Gaussian quadrature rules, method of Golub and Welsch
d01tefGenerates recursion coefficients needed by d01tdf to calculate a Gaussian quadrature rule
d01ubfNon-automatic routine to evaluate ∫0∞exp-x2fx dx
d02pgfOrdinary differential equations, initial value problem, Runge–Kutta method, integration by reverse communication
d02phfSet up interpolant by reverse communication for solution and derivative evaluations at points within the range of the last integration step taken by d02pgf
d02pjfEvaluate 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
e04mwfWrite MPS data file defining LP, QP, MILP or MIQP problem
e04rafInitialization of a handle for the NAG optimization modelling suite for problems, such as, linear programming (LP), quadratic programming (QP), nonlinear programming (NLP), least squares (LSQ) problems, linear semidefinite programming (SDP) or SDP with bilinear matrix inequalities (BMI-SDP)
e04rdfA reader of sparse SDPA data files for linear SDP problems
e04refDefine a linear objective function to a problem initialized by e04raf
e04rffDefine a linear or a quadratic objective function to a problem initialized by e04raf
e04rgfDefine a nonlinear objective function to a problem initialized by e04raf
e04rhfDefine bounds of variables of a problem initialized by e04raf
e04rjfDefine a block of linear constraints to a problem initialized by e04raf
e04rkfDefine a block of nonlinear constraints to a problem initialized by e04raf
e04rlfDefine a structure of Hessian of the objective, constraints or the Lagrangian to a problem initialized by e04raf
e04rnfAdd one or more linear matrix inequality constraints to a problem initialized by e04raf
e04rpfDefine bilinear matrix terms to a problem initialized by e04raf
e04ryfPrint information about a problem handle initialized by e04raf
e04rzfDestroy the problem handle initialized by e04raf and deallocate all the memory used
e04stfRun an interior point solver on a sparse nonlinear programming problem (NLP) initialized by e04raf and defined by other routines from the suite
e04svfRun 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)
e04zmfOption setting routine for the solvers from the NAG optimization modelling suite
e04znfOption getting routine for the solvers from the NAG optimization modelling suite
e04zpfOption setting routine for the solvers from the NAG optimization modelling suite from external file
f08vcfComputes, using BLAS-3, the generalized singular value decomposition of a real matrix pair
f08vgfProduces 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
f08vqfComputes, using BLAS-3, the generalized singular value decomposition of a complex matrix pair
f08vufProduces 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
f08wcfComputes, for a real nonsymmetric matrix pair, using BLAS-3, the generalized eigenvalues, and optionally, the left and/or right generalized eigenvectors
f08wffPerforms, using BLAS-3, an orthogonal reduction of a pair of real general matrices to generalized upper Hessenberg form
f08wqfComputes, for a complex nonsymmetric matrix pair, using BLAS-3, the generalized eigenvalues, and optionally, the left and/or right generalized eigenvectors
f08wtfPerforms, using BLAS-3, a unitary reduction of a pair of complex general matrices to generalized upper Hessenberg form
f08xcfComputes, 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
f08xqfComputes, 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
g02apfComputes a correlation matrix from an approximate one using a specified target matrix
x06xafTests whether a threaded NAG Library is being used

3
Internal Changes Affecting Users

The following routines have been significantly updated or enhanced at this mark and details are available in each routine document.
For details of all known issues which have been reported for the NAG Library please refer to the Known Issues list.

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)
c06eafc06paf
c06ebfc06paf
c06ecfc06pcf
c06ekfc06fkf
c06frfc06psf
c06fufc06puf
c06gbfNo replacement required
c06gcfNo replacement required
c06gqfNo replacement required
c06gsfNo replacement required
c06hafc06ref
c06hbfc06rff
c06hcfc06rgf
c06hdfc06rhf
d01bafd01uaf
d01bbfd01tbf
d02pcfd02pef and associated D02P routines
d02pdfd02pff or d02pgf and associated D02P routines
d02pvfd02pqf
d02pwfd02prf
d02pxfd02psf
d02pyfd02ptf
d02pzfd02puf
f04ycff04ydf
f04zcff04zdf
g01aafg01atf

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)
d02tkfd02tlf
d03ryfNo replacement required
e02acfe02alf
f02sdff12agf and f12fgf
f02wdff02wuf and f08aef (dgeqrf)
g01agfNo replacement required
g01ahfNo replacement required
g01ajfNo replacement required
g10bafg10bbf
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)
c06fpfc06pqf
c06fqfc06pqf
d01rbfNo replacement required
f04abff07fbf (dposvx)
f04aeff07abf (dgesvx)
f04asff07fbf (dposvx)
f04atff07abf (dgesvx)
NAG Library Manual, Mark 26
NAG AD Library Manual, Mark 26
NAG C Library Manual, Mark 26
© The Numerical Algorithms Group Ltd. 2018