NAG Library News, Mark 27
1
Introduction
At Mark 27, the NAG Library now consists of three main interface sets: the NAG FL Interface, the NAG CL Interface and the NAG AD Library Interfaces (see
Section 1.2). The NAG FL Interface now consists of 1908 usercallable routines while the NAG CL Interface now consists of 1619. All of these routines are fully documented and 62 are new since Mark 26. See
Section 2 for the full list of new routines which includes new routines introduced at Mark 26 point releases.
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, introduced at Mark 26.2. Supplementary documentation is provided for the NAG AD Library, including: the
Introduction to the NAG AD Library and 58 usercallable 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 two new routines that find 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 E01 (
Interpolation) has two new routines to compute a monotone convex interpolation function and to evaluate this function at a set of points. Also, a new routine is provided for efficient interpolation of data supplied on a rectangular grid, in any number of dimensions; this routine should be used for gridded data in preference to older routines which are primarily designed for interpolation of scattered data sets.
Chapter E04 (
Minimizing or Maximizing a Function) has several significant additions to the NAG optimization modelling suite:
A new set of Derivativefree Optimization (DFO) solvers for general nonlinear objective with bound constraints and for least squares (data fitting, calibration) problems with bound constraints, available with both direct and reverse communication interfaces. These solvers should show an improved convergence rate compared to the existing DFO solutions in the NAG Library. They also have features designed to specifically handle noisy or expensive problems.
A new Secondorder Cone Programming (SOCP) solver based on interior point method. This is particularly useful for many convex optimization problems, such as convex quadratically constrained quadratic programming (QCQP), which can be reformulated as SOCP.
A new Firstorder Activeset (FOAS) method for boundconstrained largescale nonlinear programming problems. The new solver is based on nonlinear conjugate gradient method, it only requires first derivatives and has low memory requirements thus is suitable for very large scale problems. It is a modern replacement for the routine
e04dgf/e04dga and shows significant improvement over it. This modern solver has robust features to deal with missing objective values, to handle missing derivative entries, and to detect slow progress.
Chapter F01 (
Matrix Operations, Including Inversion) has two new routines for computing nonnegative matrix factorizations and two new routines for computing the product of two (real and complex) triangular matrices.
Chapter F08 (
Least Squares and Eigenvalue Problems (LAPACK)) has: two (real and complex) new expert driver routines for computing the singular value decomposition (SVD) of general matrices; complex versions of the onesided Jacobi SVD and its expert driver; and, an expert driver for the SVD of a real bidiagonal matrix.
Chapter F10 (
Randomized Numerical Linear Algebra) is a new chapter containing randomized linear algebra routines including a fast random projection and a randomized SVD algorithm. Randomized linear algebra routines are expected to outperform their deterministic counterparts in terms of computational efficiency particularly on rankdeficient problems. In many cases randomized linear algebra routines can achieve the same level of accuracy as deterministic algorithms.
Chapter G02 (
Correlation and Regression Analysis) has: two new nearest correlation matrix routines, one for calculating a rankconstrained nearest correlation matrix and one that allows arbitrary elements of the input matrix to be fixed; a new routine that combines communication arrays from calls to either
g02jcf or
g02jff allowing for the preprocessing of data in parallel; and a new suite of routines that offer an alternative method of specifying linear mixed effects regression models. The model is specified using the modelling language implemented in the
Chapter G22 chapter.
The implementation of the suite of routines for calculating the Pearson productmoment correlation coefficients and correlationlike coefficients has undergone some changes. The algorithm used has not changed and the results obtained from these routines should be comparable to the results obtained from previous releases of the NAG Library. Some of the routines in the suite have been threaded by NAG and details are given in Section 8 of the individual routine documents.
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 M01 (
Sorting and Searching) has a new routine for searching a strictly ordered vector of real numbers for the elements of an unordered array of real numbers.
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}$. There is also a new routine for calculating a realvalued periodic angular Mathieu function and/or its derivative. There are also 12 vectorized versions of existing special functions which evaluate at multiple points.
1.1
Experimental Routines
At Mark 27 there are a number of routines which have been marked as ‘Experimental’. These routines have been flagged by a note at the top of the documentation.
Routines may be classified as experimental if:

(a)the interface and / or functionality of the routine may change between marks of the Library. The routine will have been designed in such a way as to minimize the number of such changes.

(b)the complexity of the routine, or suite of routines it is part of, are such that comprehensive testing is not practical. Routines classified as experimental have gone through the same testing and review processes as a normal Library routine, however it is recommended that additional care is taken when using the routine.
A routine classified as experimental may be reclassified as no longer being experimental, at which point the interface will become fixed as per a normal Library routine.
1.2
New Unified Library
At Mark 26 the NAG Fortran Library and the NAG C Library were considered as separate entities despite the fact that they shared, in large part, a common set of core algorithms.
At Mark 27 the NAG Library is a unification of these libraries, and additionally the NAG AD Library, into a single entity that can be called from many languages and environments, including C and Fortran. The NAG Library is now conceived and documented as having distinct interface sets: the NAG FL Interface, the NAG CL Interface and the NAG AD Library Interface.
1.3
Changes to NAG Documentation
At Mark 26 and at point release Mark 26.2 we made a number of changes to the documentation. This has been further developed to give you full access to a Library Manual which supports all the NAG interfaces available as part of the NAG Library.
The document "How to Use the NAG Library and its Documentation" has been replaced by two new documents,
How to Use the NAG Library and the
Guide to the NAG Library Documentation, providing general advice on how to use the Library and its documentation respectively. Interface specific information can be found in the
Introduction to the NAG Library FL Interface, the
Introduction to the NAG Library CL Interface and the
Introduction to the NAG AD Library.
On the left of each HTML page you will find navigational links to each NAG interface which will provide you with all the supporting documentation you need to use a particular interface in addition to the Keyword Search box. See
Section 7 in the Guide to the NAG Library Documentation.
On the left of each HTML page you will also find a Show Settings button which has been provided so that you can personalise your documentation to your preferred name style and specification language. See
Section 5 in the Guide to the NAG Library Documentation.
Please note that PDF is no longer provided, but most browsers provide a printtoPDF feature. See
Section 10 in the Guide to the NAG Library Documentation
Finally, 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). See
Section 5.2 in the Guide to the NAG Library Documentation.
2
New Routines since Mark 26
The lists in this section refer and link to the NAG FL Interface. In these lists there is a onetoone correspondence between the NAG FL Interface and the NAG CL Interface; and, there is a direct hyperlink from the NAG FL Interface routine document to its corresponding NAG CL Interface routine document.
The new NAG AD Library routine documents currently available are listed in the
NAG AD Library Contents and there is a direct hyperlink from the NAG FL Interface routine document to its corresponding NAG AD Library routine document, and visa versa.
2.1
New Routines at Mark 27
Routine 
Purpose 
c05mbf 
Solution of a system of nonlinear equations using Anderson acceleration 
e01cef 
Interpolating variables, monotone convex Hagan–West procedure, one variable 
e01cff 
Interpolated values, variables computed by e01cef, monotone convex Hagan–West procedure, one variable 
e01zaf 
Interpolates an $n$dimensional point on grid data using either linear, cubic or modified Shepard's method 
e04fgf 
Reverse communication derivativefree (DFO) solver for a nonlinear least squares objective function with bounded
variables 
e04jdf 
Direct communication derivativefree (DFO) solver for a nonlinear objective function with bounded variables 
e04jef 
Reverse communication derivativefree (DFO) solver for a nonlinear objective function with bounded variables 
e04kff 
First order activeset method for box constrained nonlinear optimization with low memory requirements 
e04ptf 
Solve secondorder cone programming (SOCP) and other convex related
problems, such as, quadratically constrained quadratic programming (QCQP), quadratic programming (QP), sparse, interior point method (IPM) 
e04rbf 
Define a set of variables which form a secondorder cone to a problem initialized by e04raf 
e04saf 
Load a problem from a file to a new handle for the NAG optimization
modelling suite; supported formats: extended MPS, SDPA 
f01dgf 
Matrixmatrix product, two real lower or upper triangular matrices 
f01duf 
Matrixmatrix product, two complex lower or upper triangular matrices 
f01saf 
Nonnegative matrix factorization of real nonnegative matrix 
f01sbf 
Nonnegative matrix factorization of real nonnegative matrix (reverse communication) 
f08kmf 
Computes all or selected singular values of the singular value decomposition of a real general matrix, optionally computing the corresponding left and right singular vectors 
f08kvf 
Computes the singular value decomposition of a complex matrix, optionally computing the left and/or right singular vectors (preconditioned Jacobi) 
f08kwf 
Computes the singular value decomposition of a complex matrix, optionally computing the left and/or right singular vectors (fast Jacobi) 
f08kzf 
Computes all or selected singular values of the singular value decomposition of a complex general matrix, optionally computing the corresponding left and right singular vectors 
f08mbf 
Computes all or selected singular values of the singular value decomposition of a real square bidiagonal matrix, optionally computing the corresponding left and right singular vectors 
f10caf 
Computes the singular value decomposition of a real matrix, optionally computing the left and/or right singular vectors 
f10daf 
Computes a fast random projection of a real matrix using a discrete cosine transform 
f11zcf 
Sorts and merges elements of a real sparse rectangular matrix, represented in coordinate storage format, and provides the compressed column storage format of the result 
g02akf 
Computes the rankconstrained nearest correlation matrix to a real square matrix, using the method of Qi and Sun 
g02asf 
Computes the nearest correlation matrix to a real square matrix, with fixed elements 
g02jff 
Linear mixed effects regression, initialization routine for g02jhf 
g02jgf 
Linear mixed effects regression, initialization routine for g02jgf and g02jhf 
g02jhf 
Linear mixed effects regression using either Restricted Maximum Likelihood (REML) or Maximum Likelihood (ML) 
m01ndf 
Searches an ordered set of real numbers using an $\mathit{O}\left(1\right)$ method 
s14anf 
Gamma function, vectorized $\Gamma \left(x\right)$ 
s14apf 
Log gamma function, vectorized $\mathrm{ln}\left(\Gamma \left(x\right)\right)$ 
s14bnf 
Incomplete gamma functions, vectorized $P\left(a,x\right)$ and $Q\left(a,x\right)$ 
s14cpf 
Logarithm of the beta function, vectorized $\mathrm{ln}B\left(a,b\right)$ 
s14cqf 
Regularized incomplete beta function, vectorized ${I}_{x}\left(a,b\right)$ and its complement $1{I}_{x}$ 
s15apf 
Cumulative Normal distribution function, vectorized $P\left(x\right)$ 
s15aqf 
Complement of cumulative Normal distribution function, vectorized $Q\left(x\right)$ 
s15arf 
Complement of error function, vectorized $\mathrm{erfc}\left(x\right)$ 
s15asf 
Error function, vectorized $\mathrm{erf}\left(x\right)$ 
s15atf 
Dawson's integral, vectorized 
s15auf 
Scaled complement of error function, vectorized $\mathrm{erfcx}\left(x\right)$ 
s15drf 
Scaled complex complement of error function, vectorized $\mathrm{exp}\left({z}^{2}\right)\mathrm{erfc}\left(iz\right)$ 
s22caf 
Calculates values of real periodic angular Mathieu functions 
2.2
New Routines at Mark 26.2
The NAG Library at Mark 26.2 included the first release of the NAG AD Library. See the
NAG AD Library Contents.
2.3
New Routines at Mark 26.1
Routine 
Purpose 
c05mdf 
Solution of a system of nonlinear equations using Anderson acceleration (reverse communication) 
c06saf 
Multidimensional fast Gauss transform 
e04fff 
Derivativefree (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 for a problem initialized by e04raf 
e04rxf 
Insert or extract data relating to a problem 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 
3
Internal Changes Affecting the User and Other Known Issues
The argument names of some routines have changed to be more consistent, particularly with regard to the names of usersupplied routine arguments. This will only affect those program units that use the FL Interface and also use the Fortran argument keyword facility to call routines which have new argument names. For example,
Call d01fcf(... , functn=myfun, ...)
becomes, at Mark 27,
Call d01fcf(..., f=myfun, ...)
where
myfun is the usersupplied function argument.
The following routines have been significantly updated or enhanced since Mark 26 and details are available in each routine document.
Routine 
Summary of the changes 
e01sgf

The algorithm used by this routine has been changed to produce more reliable results and work better on certain data sets.

e01shf

The algorithm used by this routine
has been changed to produce more reliable results and work
better on certain data sets.

e01tgf

The algorithm used by this routine
has been changed to produce more reliable results and work
better on certain data sets.

e01thf

The algorithm used by this routine
has been changed to produce more reliable results and work
better on certain data sets.

e01tkf

The algorithm used by this routine
has been changed to produce more reliable results and work
better on certain data sets.

e01tlf

The algorithm used by this routine
has been changed to produce more reliable results and work
better on certain data sets.

e01tmf

The algorithm used by this routine
has been changed to produce more reliable results and work
better on certain data sets.

e01tnf

The algorithm used by this routine
has been changed to produce more reliable results and work
better on certain data sets.

e01zmf

The algorithm used by this routine
has been changed to produce more reliable results and work
better on certain data sets.

e01znf

The algorithm used by this routine
has been changed to produce more reliable results and work
better on certain data sets.

e04ffc

The underlying algorithm has been improved, improving performance, and new options have been provided.

e04fff

The underlying algorithm has been improved, improving performance, and new options have been provided.

e04rhc

Some limitations on specifying model fixed variables have been lifted.

e04rhf

Some limitations on specifying model fixed variables have been lifted.

e04stc

The name of the monitoring argument has been changed to
monit, and there have been changes to the optional parameters.

e04stf

The name of the monitoring argument has been changed to
monit, and there have been changes to the optional parameters.

e04svc

Additional error check for unsupported models.

e04svf

Additional error check for unsupported models.

f11zaf

The example for this routine has been extended to show how the routine can be used to add sparse matrices, and to demonstrate conversion of sparse matrices between Coordinate Storage and Compressed Column Storage formats.

g01fbc

The algorithm underlying this routine has been altered to improve the accuracy in cases where $\mathbf{df}<3$.

g01fbf

The algorithm underlying this routine has been altered to improve the accuracy in cases where $\mathbf{df}<3$.

g02baf

The algorithm underlying this routine has been altered to improve efficiency for large problem sizes on a multithreaded system.

g02bbf

The algorithm underlying this routine has been altered to improve efficiency for large problem sizes on a multithreaded system.

g02bcf

The algorithm underlying this routine has been altered to improve efficiency for large problem sizes on a multithreaded system.

g02bdf

The algorithm underlying this routine has been altered to improve efficiency for large problem sizes on a multithreaded system.

g02bef

The algorithm underlying this routine has been altered to improve efficiency for large problem sizes on a multithreaded system.

g02bff

The algorithm underlying this routine has been altered to improve efficiency for large problem sizes on a multithreaded system.

g02bgf

The algorithm underlying this routine has been altered to improve efficiency for large problem sizes on a multithreaded system.

g02bhf

The algorithm underlying this routine has been altered to improve efficiency for large problem sizes on a multithreaded system.

g02bjf

The algorithm underlying this routine has been altered to improve efficiency for large problem sizes on a multithreaded system.

g02bkf

The algorithm underlying this routine has been altered to improve efficiency for large problem sizes on a multithreaded system.

g02blf

The algorithm underlying this routine has been altered to improve efficiency for large problem sizes on a multithreaded system.

g02dac

Corrections made to the documented array sizes and improvements made to the example program.

g02dgc

Corrections made to the documented array sizes and improvements made to the example program.

g02jdc

The algorithm underlying this routine has been altered to improve efficiency.

g02jdf

The algorithm underlying this routine has been altered to improve efficiency.

g02jec

The algorithm underlying this routine has been altered to improve efficiency.

g02jef

The algorithm underlying this routine has been altered to improve efficiency.

g22ybc

Functionality has been expanded, an additional argument has been added to the interface and some of the error exits have been renumbered.

g22ybf

Functionality has been expanded, an additional argument has been added to the interface and some of the error exits have been renumbered.

For details of all known issues which have been reported for the NAG Library please refer to the Known Issues lists for the Library
FL Interface and
CL Interface.
4
Withdrawn or Deprecated Routines
The following routines have been withdrawn or deprecated from the NAG FL Interface since Mark 26.
Also listed are routines from the CL interface if they have no FL equivalent. Warning of their withdrawal has been included in the NAG Library Manual since Mark 25, together with advice on which routines to use instead.
Please note that unless a Mark of Withdrawal is shown below, the routine will continue to form part of the Library but you are advised to stop using the deprecated routines and to use the recommended replacement routines instead.
Please see the chapter introduction documents and the ‘
FL Interface Replacement Calls Advice’ (or the CL version ‘
CL Interface Replacement Calls Advice’) for more detailed guidance, including advice on how to change a call to the deprecated routine into a call to its recommended replacement, or use the links provided in the following table.