NAG C Library

NAG C Library News, Mark 26

1
Introduction

At Mark 26, the NAG Library now contains 1575 user-callable functions, all of which are documented, of which 57 are new.
In collaboration with the group Informatik 12: Software and Tools for Computational Engineering from RWTH Aachen University, the Library now also includes the initial version of the NAG AD Library. Supplementary documentation is provided for the NAG AD Library, including: the NAG AD Library Introduction, X10, and 19 user-callable routine documents listed in the NAG AD Library Contents.
Please be advised that when you visit the NAG AD Library Contents you are being redirected out of the NAG C Library Manual to the main NAG Library Manual. In the NAG Library Manual you will see that the specification of functions in function documents (see for example Section 2 in d03pdf) now includes the C Header interface which can be used to call a NAG Library function from C or C++.
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 function that finds a solution of a system of nonlinear equations using Anderson acceleration.
Chapter c06 (Fourier Transforms) has a new function that calculates the fast Gauss transform approximation to the discrete Gauss transform.
Chapter d01 (Quadrature) has two new functions to calculate weights and abscissae for use in Gaussian quadrature and a new function to solve a specific Gaussian quadrature problem.
Chapter e04 (Minimizing or Maximizing a Function) has a new suite of functions, 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 functions 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 function that, using a shrinking method, allows the fixing of arbitrary elements in the input matrix.
Chapter g04 (Analysis of Variance) has a new function 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 functions to evaluate Struve functions H0, H1, L0 and L1.
Chapter x06 (OpenMP Utilities) has a new function to identify, at runtime, whether you are using a threaded Library or not.
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.
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 Functions 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 Functions at Mark 26.1

The 20 new user-callable functions included in the NAG C Library at Mark 26.1 are as follows.
Function
Name

Purpose
c05mdcSolution of a system of nonlinear equations using Anderson acceleration (reverse communication)
c06sacMultidimensional fast Gauss transform
e04ffcDerivative-free (DFO) solver for a nonlinear least squares objective function with bounded variables
e04mtcLinear programming (LP), sparse, interior point method (IPM)
e04rmcDefine a nonlinear least squares objective function to a problem initialized by nag_opt_handle_init (e04rac)
e04rxcRetrieve or write a piece of information in a problem handle initialized by nag_opt_handle_init (e04rac)
g04gacIntraclass correlation (ICC) for assessing rater reliability
g22yacSpecify a linear model via a formula string
g22ybcDescribe a dataset
g22yccConstruct a design matrix from a linear model specified using nag_blgm_lm_formula (g22yac)
g22ydcConstruct a vector indicating which columns of a design matrix to include in a submodel specified using nag_blgm_lm_formula (g22yac)
g22zacDestroy a G22 handle and deallocate all the memory used
g22zmcOption setting function for Chapter g22
g22zncOption getting function for Chapter g22
s17gacStruve function of order 0, H0x
s17gbcStruve function of order 1, H1x
s18gacModified Struve function of order 0, L0x
s18gbcModified Struve function of order 1, L1x
s18gccThe function I0x-L0x, where I0x is a modified Bessel function and L0x is a Struve function
s18gdcThe function I1x-L1x, where I1x is a modified Bessel function and L1x is a Struve function

2.3
New Functions at Mark 26.0

The 37 new user-callable functions included in the NAG C Library at Mark 26.0 are as follows.
Function
Name

Purpose
d01tdcCalculation of weights and abscissae for Gaussian quadrature rules, method of Golub and Welsch
d01tecGenerates recursion coefficients needed by nag_quad_1d_gauss_wrec (d01tdc) to calculate a Gaussian quadrature rule
d01ubcNon-automatic function to evaluate 0exp-x2fx dx
d02pgcOrdinary differential equations, initial value problem, Runge–Kutta method, integration by reverse communication
d02phcSet up interpolant by reverse communication for solution and derivative evaluations at points within the range of the last integration step taken by nag_ode_ivp_rk_step_revcomm (d02pgc)
d02pjcEvaluate interpolant, set up using nag_ode_ivp_rkts_setup (d02pqc), to approximate solution and/or solution derivatives at a point within the range of the last integration step taken by nag_ode_ivp_rk_step_revcomm (d02pgc)
e04mwcWrite MPS data file defining LP, QP, MILP or MIQP problem
e04racInitialization 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)
e04rdcA reader of sparse SDPA data files for linear SDP problems
e04recDefine a linear objective function to a problem initialized by nag_opt_handle_init (e04rac)
e04rfcDefine a linear or a quadratic objective function to a problem initialized by nag_opt_handle_init (e04rac)
e04rgcDefine a nonlinear objective function to a problem initialized by nag_opt_handle_init (e04rac)
e04rhcDefine bounds of variables of a problem initialized by nag_opt_handle_init (e04rac)
e04rjcDefine a block of linear constraints to a problem initialized by nag_opt_handle_init (e04rac)
e04rkcDefine a block of nonlinear constraints to a problem initialized by nag_opt_handle_init (e04rac)
e04rlcDefine a structure of Hessian of the objective, constraints or the Lagrangian to a problem initialized by nag_opt_handle_init (e04rac)
e04rncAdd one or more linear matrix inequality constraints to a problem initialized by nag_opt_handle_init (e04rac)
e04rpcDefine bilinear matrix terms to a problem initialized by nag_opt_handle_init (e04rac)
e04rycPrint information about a problem handle initialized by nag_opt_handle_init (e04rac)
e04rzcDestroy the problem handle initialized by nag_opt_handle_init (e04rac) and deallocate all the memory used
e04stcRun an interior point solver on a sparse nonlinear programming problem (NLP) initialized by nag_opt_handle_init (e04rac) and defined by other functions from the suite
e04svcRun the Pennon solver on a compatible problem initialized by nag_opt_handle_init (e04rac) and defined by other functions from the suite, such as, semidefinite programming (SDP) and SDP with bilinear matrix inequalities (BMI)
e04zmcOption setting routine for the solvers from the NAG optimization modelling suite
e04zncOption getting routine for the solvers from the NAG optimization modelling suite
e04zpcOption setting routine for the solvers from the NAG optimization modelling suite from external file
f08vccComputes, using BLAS-3, the generalized singular value decomposition of a real matrix pair
f08vgcProduces 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
f08vqcComputes, using BLAS-3, the generalized singular value decomposition of a complex matrix pair
f08vucProduces 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
f08wccComputes, for a real nonsymmetric matrix pair, using BLAS-3, the generalized eigenvalues, and optionally, the left and/or right generalized eigenvectors
f08wfcPerforms, using BLAS-3, an orthogonal reduction of a pair of real general matrices to generalized upper Hessenberg form
f08wqcComputes, for a complex nonsymmetric matrix pair, using BLAS-3, the generalized eigenvalues, and optionally, the left and/or right generalized eigenvectors
f08wtcPerforms, using BLAS-3, a unitary reduction of a pair of complex general matrices to generalized upper Hessenberg form
f08xccComputes, 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
f08xqcComputes, 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
g02apcComputes a correlation matrix from an approximate one using a specified target matrix
x06xacTests whether a threaded NAG Library is being used

3
Internal Changes Affecting Users

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

4
Withdrawn Functions

The following functions have been withdrawn from the NAG C Library at Mark 26. Warning of their withdrawal was included in the NAG C Library Manual at Mark 25, together with advice on which functions to use instead. See the document ‘Advice on Replacement Calls for Withdrawn/Superseded Functions’ for more detailed guidance.
Withdrawn
Function

Replacement Function(s)
c06eacnag_sum_fft_realherm_1d (c06pac)
c06ebcnag_sum_fft_realherm_1d (c06pac)
c06eccnag_sum_fft_complex_1d (c06pcc)
c06ekcnag_sum_convcorr_real (c06fkc)
c06frcnag_sum_fft_complex_1d_multi (c06psc)
c06fucnag_sum_fft_complex_2d (c06puc)
c06gbcNo replacement required
c06gccNo replacement required
c06hacnag_sum_fft_sine (c06rec)
c06hbcnag_sum_fft_cosine (c06rfc)
c06hccnag_sum_fft_qtrsine (c06rgc)
c06hdcnag_sum_fft_qtrcosine (c06rhc)
d02pccnag_ode_ivp_rkts_range (d02pec) and associated d02p functions
d02pdcnag_ode_ivp_rkts_onestep (d02pfc) and associated d02p functions
d02ppcNo replacement required
d02pvcnag_ode_ivp_rkts_setup (d02pqc)
d02pwcnag_ode_ivp_rkts_reset_tend (d02prc)
d02pxcnag_ode_ivp_rkts_interp (d02psc)
d02pzcnag_ode_ivp_rkts_errass (d02puc)
e04jbcnag_opt_nlp (e04ucc)
f02aacnag_dsyev (f08fac)
f02abcnag_dsyev (f08fac)
f02adcnag_dsygv (f08sac)
f02aecnag_dsygv (f08sac)
f02afcnag_dgeev (f08nac)
f02agcnag_dgeev (f08nac)
f02awcnag_zheev (f08fnc)
f02axcnag_zheev (f08fnc)
f02bjcnag_dggev (f08wac)
f02wecnag_dgesvd (f08kbc)
f02xecnag_zgesvd (f08kpc)
g01aacnag_summary_stats_onevar (g01atc)
g10bacnag_kernel_density_gauss (g10bbc)

5
Functions Scheduled for Withdrawal

The functions listed below are scheduled for withdrawal from the NAG C Library, because improved functions have now been included in the Library. You are advised to stop using functions which are scheduled for withdrawal and to use recommended replacement functions instead. See the document ‘Advice on Replacement Calls for Withdrawn/Superseded Functions’ for more detailed guidance, including advice on how to change a call to the old function into a call to its recommended replacement.
The following functions have been superseded, but will not be withdrawn from the Library until Mark 28 at the earliest.
Superseded
Function

Replacement Function(s)
d01tacnag_quad_1d_gauss_vec (d01uac)