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 user-callable 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 user-callable routine documents listed in the FL Interface 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 Derivative-free 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 Second-order 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 First-order Active-set (FOAS) method for bound-constrained large-scale 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 non-negative 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 one-sided 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 rank-deficient 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 rank-constrained 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 pre-processing 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 product-moment correlation coefficients and correlation-like 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 H0, H1, L0 and L1. There is also a new routine for calculating a real-valued 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:
  1. (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.
  2. (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 print-to-PDF 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 one-to-one 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 FL Interface 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 derivative-free (DFO) solver for a nonlinear least squares objective function with bounded variables
e04jdf Direct communication derivative-free (DFO) solver for a nonlinear objective function with bounded variables
e04jef Reverse communication derivative-free (DFO) solver for a nonlinear objective function with bounded variables
e04kff First-order active-set method for box constrained nonlinear optimization with low memory requirements
e04ptf Solve second-order 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 second-order 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 Matrix-matrix product, two real lower or upper triangular matrices
f01duf Matrix-matrix product, two complex lower or upper triangular matrices
f01saf Non-negative matrix factorization of real non-negative matrix
f01sbf Non-negative matrix factorization of real non-negative 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 rank-constrained 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 O1 method
s14anf Gamma function, vectorized Γx
s14apf Log gamma function, vectorized lnΓx
s14bnf Incomplete gamma functions, vectorized Pa,x and Qa,x
s14cpf Logarithm of the beta function, vectorized lnBa,b
s14cqf Regularized incomplete beta function, vectorized Ixa,b and its complement 1-Ix
s15apf Cumulative Normal distribution function, vectorized Px
s15aqf Complement of cumulative Normal distribution function, vectorized Qx
s15arf Complement of error function, vectorized erfcx
s15asf Error function, vectorized erfx
s15atf Dawson's integral, vectorized
s15auf Scaled complement of error function, vectorized erfcxx
s15drf Scaled complex complement of error function, vectorized exp-z2erfc-iz
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 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 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, H0x
s17gbf Struve function of order 1, H1x
s18gaf Modified Struve function of order 0, L0x
s18gbf Modified Struve function of order 1, L1x
s18gcf The function I0x-L0x, where I0x is a modified Bessel function and L0x is a Struve function
s18gdf The function I1x-L1x, where I1x is a modified Bessel function and L1x 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 user-supplied 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 user-supplied 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 df<3.
g01fbf The algorithm underlying this routine has been altered to improve the accuracy in cases where df<3.
g02baf The algorithm underlying this routine has been altered to improve efficiency for large problem sizes on a multi-threaded system.
g02bbf The algorithm underlying this routine has been altered to improve efficiency for large problem sizes on a multi-threaded system.
g02bcf The algorithm underlying this routine has been altered to improve efficiency for large problem sizes on a multi-threaded system.
g02bdf The algorithm underlying this routine has been altered to improve efficiency for large problem sizes on a multi-threaded system.
g02bef The algorithm underlying this routine has been altered to improve efficiency for large problem sizes on a multi-threaded system.
g02bff The algorithm underlying this routine has been altered to improve efficiency for large problem sizes on a multi-threaded system.
g02bgf The algorithm underlying this routine has been altered to improve efficiency for large problem sizes on a multi-threaded system.
g02bhf The algorithm underlying this routine has been altered to improve efficiency for large problem sizes on a multi-threaded system.
g02bjf The algorithm underlying this routine has been altered to improve efficiency for large problem sizes on a multi-threaded system.
g02bkf The algorithm underlying this routine has been altered to improve efficiency for large problem sizes on a multi-threaded system.
g02blf The algorithm underlying this routine has been altered to improve efficiency for large problem sizes on a multi-threaded 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. 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.
Routine Status Replacement Routine(s)
c06fpf To be withdrawn at Mark 28 c06ppf or c06pqf
c06fqf To be withdrawn at Mark 28 c06ppf or c06pqf
c06gqc To be withdrawn at Mark 29 No replacement required
c06gsc To be withdrawn at Mark 29 No replacement required
c06gzc To be withdrawn at Mark 29 No replacement required
d01rbf To be withdrawn at Mark 28 No replacement required
d01tac To be withdrawn at Mark 28 d01uac
d02tkf Withdrawn at Mark 27 d02tlf
d03ryf Withdrawn at Mark 27 No replacement required
e02acf Withdrawn at Mark 27 e02alf
e04dgf Deprecated e04kff
e04jcf Deprecated e04jdf and e04jef
f02sdf Withdrawn at Mark 27 f12agf and f12fgf
f02wdf Withdrawn at Mark 27 f08aef and f02wuf
f04abf To be withdrawn at Mark 28 f07fbf
f04aef To be withdrawn at Mark 28 f07abf
f04asf To be withdrawn at Mark 28 f07fbf
f04atf To be withdrawn at Mark 28 f07abf
f08bef Deprecated f08bff
f08bsf Deprecated f08btf
f08vaf Deprecated f08vcf
f08vef Deprecated f08vgf
f08vnf Deprecated f08vqf
f08vsf Deprecated f08vuf
f08waf Deprecated f08wcf
f08wef Deprecated f08wff
f08wnf Deprecated f08wqf
f08wsf Deprecated f08wtf
f08xaf Deprecated f08xcf
f08xnf Deprecated f08xqf
g01agf Withdrawn at Mark 27 No replacement required
g01ahf Withdrawn at Mark 27 No replacement required
g01ajf Withdrawn at Mark 27 No replacement required
g02jaf Deprecated g02jff followed by g02jhf
g02jbf Deprecated g02jff followed by g02jhf
g02jcf Deprecated g02jff
g02jdf Deprecated g02jhf
g02jef Deprecated g02jhf
g10baf Withdrawn at Mark 27 g10bbf