# NAG Library

## 1Introduction

At Mark 26 of the NAG Library new functionality has been introduced in addition to improvements in existing areas. The Library now contains 1875 user-callable routines, all of which are documented, of which 57 are new at this mark. Further new functionality has been introduced at Mark 26.1
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, 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.
At Mark 26.1, two new solvers are added to the NAG Modelling Optimization Suite. The first one is a derivative free solver for nonlinear least squares subject to bound constraints. It is 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 one 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 G22 (Linear Model Specification) contains utility routines for aiding in the construction of design matrices for use when fitting linear regression models.
Chapter S (Approximations of Special Functions) contains a new set of routines to evaluate Struve functions ${H}_{0}$, ${H}_{1}$, ${L}_{0}$ and ${L}_{1}$.
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 a number of changes to the documentation and long names as follows.
The specification of routines in routine documents (see 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 consistently use the Chapter identifying word (e.g., ‘opt’ for Chapter E04) as the second word in the long name. (b) 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. (c) the word ‘withdrawn’ has been changed to ‘withdraw’ to be consistent with other routine long names using ‘withdraw’. (d) ‘withdraw_’ has been removed from a few routines that are no longer to be withdrawn.
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.

## 2New Routines

### 2.1New Routines at Mark 26.1

The 20 new user-callable routines included in the NAG Library at Mark 26.1 are as follows.
 RoutineName Purpose c05mdf Solution of a system of nonlinear equations using Anderson acceleration (reverse communication) c06saf Multidimensional fast Gauss transform e04fff Derivative free (DFO) solver for a nonlinear least squares objective function with bounded variables e04mtf Linear programming (LP), sparse, interior point method (IPM) e04rmf Define a nonlinear least squares objective function to a problem initialized by e04raf e04rxf Retrieve or write a piece of information in a problem handle initialized by e04raf g04gaf Intraclass correlation (ICC) for assessing rater reliability g22yaf Specify a linear model via a formula string g22ybf Describe a dataset g22ycf Construct a design matrix from a linear model specified using g22yaf g22ydf Construct a vector indicating which columns of a design matrix to include in a submodel specified using g22yaf g22zaf Destroy a G22 handle and deallocate all the memory used g22zmf Option setting routine for Chapter G22 g22znf Option getting routine for Chapter G22 s17gaf Struve function of order $0$, ${H}_{0}\left(x\right)$ s17gbf Struve function of order $1$, ${H}_{1}\left(x\right)$ s18gaf Modified Struve function of order $0$, ${L}_{0}\left(x\right)$ s18gbf Modified Struve function of order $1$, ${L}_{1}\left(x\right)$ s18gcf The function ${I}_{0}\left(x\right)-{L}_{0}\left(x\right)$, where ${I}_{0}\left(x\right)$ is a modified Bessel function and ${L}_{0}\left(x\right)$ is a Struve function s18gdf The function ${I}_{1}\left(x\right)-{L}_{1}\left(x\right)$, where ${I}_{1}\left(x\right)$ is a modified Bessel function and ${L}_{1}\left(x\right)$ is a Struve function

### 2.2New Routines at Mark 26.0

The 37 new user-callable routines included in the NAG Library at Mark 26.0 are as follows.
 RoutineName 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 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, 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) 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

## 3Internal 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.

## 4Withdrawn 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.
 WithdrawnRoutine 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

## 5Routines 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 Scheduledfor Withdrawal Replacement Routine(s) d02tkf d02tlf d03ryf No replacement required e02acf e02alf f02sdf f12agf and f12fgf f02wdf f02wuf and f08aef (dgeqrf) g01agf No replacement required g01ahf No replacement required g01ajf No replacement required g10baf g10bbf
The following routines have been superseded, but will not be withdrawn from the Library until Mark 28 at the earliest.
 SupersededRoutine Replacement Routine(s) c06fpf c06pqf c06fqf c06pqf d01rbf No replacement required f04abf f07fbf (dposvx) f04aef f07abf (dgesvx) f04asf f07fbf (dposvx) f04atf f07abf (dgesvx)
© The Numerical Algorithms Group Ltd, Oxford, UK. 2017