NAG Library Manual

# NAG LibraryNAG C Library News, Mark 24

## 1  Introduction

At Mark 24 of the NAG C Library new functionality has been introduced in addition to improvements in existing areas. The Library now contains 1516 user-callable functions, all of which are documented, of which 148 are new at this mark.
A major feature at this mark is the incorporation of SMP capability into the C Library. Consequently the C Library documentation is being enhanced to indicate which functions are capable of utilizing threads.
A new Chapter x07 (IEEE Arithmetic) has been introduced, providing functions relating to IEEE arithmetic such as determining or creating an infinite value or a NaN (Not a Number). There have also been extensions in functionality included in the areas of statistics, wavelets, ordinary differential equations, interpolation, surface fitting, optimization, matrix operations, linear algebra, operations research, and special functions.
Chapter c06 (Fourier Transforms) has Fast Fourier Transforms (FFTs) for two-dimensional and three-dimensional real data, and replacement functions for transforms of complex data and symmetric transforms of real data removing restrictions on sequence length.
Chapter c09 (Wavelet Transforms) has new functions for computing the three-dimensional discrete wavelet transform (DWT) and its inverse, including applying the DWT over multiple levels (c09f*c). These functions are threaded for parallelism in some implementations. In addition there are new functions for inserting coefficients into and extracting coefficients from the compact form used in the multilevel two-dimensional functions and all three-dimensional functions, which would make working with the DWT functions easier as demonstrated in the examples. There are also functions for the maximal overlap discrete wavelet transform (MODWT) and its inverse in one dimension, which are useful in time series analysis.
Chapter d02 (Ordinary Differential Equations) has a suite of functions solving Boundary Value Problems by the collocation method, and a replacement for the suite implementing Runge–Kutta methods for non-stiff Initial Value Problems.
Chapter e01 (Interpolation) has the modified Shepard's method for interpolating in dimensions greater than $5$.
Chapter e02 (Curve and Surface Fitting) has a two-stage approximation method for two-dimensional scattered data.
Chapter e04 (Minimizing or Maximizing a Function) has non-negative least squares and an improved MPS data reader.
Chapter e05 (Global Optimization of a Function) has a multi-start version of a least squares with nonlinear constraints function.
Chapter f01 (Matrix Operations, Including Inversion) has greatly extended its range of matrix functions. New and improved algorithms are available for the matrix logarithm, the matrix square root, the matrix exponential and general matrix powers. We also now have functions for computing Fréchet derivatives.
Chapter f02 (Eigenvalues and Eigenvectors) has functions for the solution of the real and complex quadratic eigenvalue problem, and a driver function for calculating selected eigenvalues/vectors of general sparse matrices.
Chapter f04 (Simultaneous Linear Equations) has norm estimators for rectangular matrices.
Chapter f08 (Least Squares and Eigenvalue Problems (LAPACK)) has functions for recursive, explicitly blocked $QR$ factorization and applying $Q$ for general matrices and for triangular-pentagonal matrices, and has functions for the complete CS decomposition of an orthogonal or unitary matrix.
Chapter f11 (Large Scale Linear Systems) has a block diagonal (possibly overlapping) preconditioner and associated solver for real and complex nonsymmetric sparse matrices.
Chapter f12 (Large Scale Eigenproblems) has a driver for selected eigenvalues/vectors of general banded complex eigenproblems.
Chapter f16 (NAG Interface to BLAS) has two additions from the BLAST set of functions.
Chapter g01 (Simple Calculations on Statistical Data) has functions for calculating summary statistics in a rolling window and combining summary statistics calculated on different data streams as well as a function for calculating probabilities from a multivariate Student's $t$-distribution.
Chapter g02 (Correlation and Regression Analysis) has functions for weighted nearest correlation matrix and calculating sums of squares matrices (and hence correlation and covariance matrices) on streamed data.
Chapter g03 (Multivariate Methods) has a Gaussian mixture model function.
Chapter g05 (Random Number Generators) has Brownian bridge and random field functions.
Chapter g13 (Time Series Analysis) has functions for analysing inhomogeneous time series.
Chapter h (Operations Research) has functions for feature subset selections.
Chapter s (Approximations of Special Functions) has confluent and Gauss hypergeometric functions ${}_{1}F_{1}\left(a,b;x\right)$ and ${}_{2}F_{1}\left(a,b;c;x\right)$, and a new derivative pricing function extends the Heston stochastic volatility model to incorporate a term structure which can facilitate calibration to market data.

## 2  New Functions

The 148 new user-callable functions included in the NAG C Library at Mark 24 are as follows.
 FunctionName Purpose c06fkc Circular convolution or correlation of two real vectors, no restrictions on $n$ c06pac Single one-dimensional real and Hermitian complex discrete Fourier transform, using complex storage format for Hermitian sequences c06pcc Single one-dimensional complex discrete Fourier transform, complex data type c06psc Multiple one-dimensional complex discrete Fourier transforms, complex data type c06puc Two-dimensional complex discrete Fourier transform, complex data type c06pvc Two-dimensional real-to-complex discrete Fourier transform c06pwc Two-dimensional complex-to-real discrete Fourier transform c06pyc Three-dimensional real-to-complex discrete Fourier transform c06pzc Three-dimensional complex-to-real discrete Fourier transform c06rec Multiple discrete sine transforms, simple c06rfc Multiple discrete cosine transforms, simple c06rgc Multiple discrete quarter-wave sine transforms, simple c06rhc Multiple discrete quarter-wave cosine transforms, simple c09acc Three-dimensional wavelet filter initialization c09dac One-dimensional maximal overlap discrete wavelet transform (MODWT) c09dbc One-dimensional inverse maximal overlap discrete wavelet transform (IMODWT) c09dcc One-dimensional multi-level maximal overlap discrete wavelet transform (MODWT) c09ddc One-dimensional inverse multi-level maximal overlap discrete wavelet transform (IMODWT) c09eyc Two-dimensional discrete wavelet transform coefficient extraction c09ezc Two-dimensional discrete wavelet transform coefficient insertion c09fac Three-dimensional discrete wavelet transform c09fbc Three-dimensional inverse discrete wavelet transform c09fcc Three-dimensional multi-level discrete wavelet transform c09fdc Three-dimensional inverse multi-level discrete wavelet transform c09fyc Three-dimensional discrete wavelet transform coefficient extraction c09fzc Three-dimensional discrete wavelet transform coefficient insertion d01rac One-dimensional quadrature, adaptive, finite interval, multiple integrands, vectorized abscissae, reverse communication d01rcc Determine required array dimensions for nag_quad_1d_gen_vec_multi_rcomm (d01rac) d01rgc One-dimensional quadrature, adaptive, finite interval, strategy due to Gonnet, allowing for badly behaved integrands d01uac One-dimensional Gaussian quadrature, choice of weight functions (vectorized) d01zkc Option setting function d01zlc Option getting function d02pec Ordinary differential equations, initial value problem, Runge–Kutta method, integration over range with output d02pfc Ordinary differential equations, initial value problem, Runge–Kutta method, integration over one step d02pqc Ordinary differential equations, initial value problem, setup for nag_ode_ivp_rkts_range (d02pec) and nag_ode_ivp_rkts_onestep (d02pfc) d02prc Ordinary differential equations, initial value problem, resets end of range for nag_ode_ivp_rkts_onestep (d02pfc) d02psc Ordinary differential equations, initial value problem, interpolation for nag_ode_ivp_rkts_onestep (d02pfc) d02ptc Ordinary differential equations, initial value problem, integration diagnostics for nag_ode_ivp_rkts_range (d02pec) and nag_ode_ivp_rkts_onestep (d02pfc) d02puc Ordinary differential equations, initial value problem, error assessment diagnostics for nag_ode_ivp_rkts_range (d02pec) and nag_ode_ivp_rkts_onestep (d02pfc) d02tlc Ordinary differential equations, general nonlinear boundary value problem, collocation technique d02tvc Ordinary differential equations, general nonlinear boundary value problem, setup for nag_ode_bvp_coll_nlin_solve (d02tlc) d02txc Ordinary differential equations, general nonlinear boundary value problem, continuation facility for nag_ode_bvp_coll_nlin_solve (d02tlc) d02tyc Ordinary differential equations, general nonlinear boundary value problem, interpolation for nag_ode_bvp_coll_nlin_solve (d02tlc) d02tzc Ordinary differential equations, general nonlinear boundary value problem, diagnostics for nag_ode_bvp_coll_nlin_solve (d02tlc) e01zmc Interpolating function, modified Shepard's method, $d$ dimensions e01znc Interpolated values, evaluate interpolant computed by nag_nd_shep_interp (e01zmc), function and first derivatives, $d$ dimensions e02alc Minimax curve fit by polynomials e02bfc Evaluation of fitted cubic spline, function and optionally derivatives at a vector of points e02jdc Spline approximation to a set of scattered data using a two-stage approximation method e02jec Evaluation at a vector of points of a spline computed by nag_2d_spline_fit_ts_scat (e02jdc) e02jfc Evaluation at a mesh of points of a spline computed by nag_2d_spline_fit_ts_scat (e02jdc) e02zkc Option setting routine e02zlc Option getting routine e04mxc Reads MPS data file defining LP, QP, MILP or MIQP problem e04pcc Computes the least squares solution to a set of linear equations subject to fixed upper and lower bounds on the variables. An option is provided to return a minimal length solution if a solution is not unique e05usc Global optimization of a sum of squares problem using multi-start, nonlinear constraints f01elc Function of a real matrix (using numerical differentiation) f01enc Real matrix square root f01epc Real upper quasi-triangular matrix square root f01eqc General power of a real matrix f01flc Function of a complex matrix (using numerical differentiation) f01fnc Complex matrix square root f01fpc Complex upper triangular matrix square root f01fqc General power of a complex matrix f01gac Action of a real matrix exponential on a real matrix f01gbc Action of a real matrix exponential on a real matrix (reverse communication) f01hac Action of a complex matrix exponential on a complex matrix f01hbc Action of a complex matrix exponential on a complex matrix (reverse communication) f01jac Condition number for the exponential, logarithm, sine, cosine, sinh or cosh of a real matrix f01jbc Condition number for a function of a real matrix (using numerical differentiation) f01jcc Condition number for a function of a real matrix (using user-supplied derivatives) f01jdc Condition number for square root of real matrix f01jec Condition number for real matrix power f01jfc Fréchet derivative of real matrix power f01jgc Condition number for real matrix exponential f01jhc Fréchet derivative of real matrix exponential f01jjc Condition number for real matrix logarithm f01jkc Fréchet derivative of real matrix logarithm f01kac Condition number for the exponential, logarithm, sine, cosine, sinh or cosh of a complex matrix f01kbc Condition number for a function of a complex matrix (using numerical differentiation) f01kcc Condition number for a function of a complex matrix (using user-supplied derivatives) f01kdc Condition number for square root of complex matrix f01kec Condition number for complex matrix power f01kfc Fréchet derivative of complex matrix power f01kgc Condition number for complex matrix exponential f01khc Fréchet derivative of complex matrix exponential f01kjc Condition number for complex matrix logarithm f01kkc Fréchet derivative of complex matrix logarithm f02ekc Selected eigenvalues and eigenvectors of a real sparse general matrix f02jcc Solves the quadratic eigenvalue problem for real matrices f02jqc Solves the quadratic eigenvalue problem for complex matrices f04ydc Norm estimation (for use in condition estimation), real rectangular matrix f04zdc Norm estimation (for use in condition estimation), complex rectangular matrix f08abc Performs a $QR$ factorization of real general rectangular matrix, with explicit blocking f08acc Applies the orthogonal transformation determined by nag_dgeqrt (f08abc) f08apc Performs a $QR$ factorization of complex general rectangular matrix using recursive algorithm f08aqc Applies the unitary transformation determined by nag_zgeqrt (f08apc) f08bbc $QR$ factorization of real general triangular-pentagonal matrix f08bcc Applies the orthogonal transformation determined by nag_dtpqrt (f08bbc) f08bpc $QR$ factorization of complex triangular-pentagonal matrix f08bqc Applies the unitary transformation determined by nag_ztpqrt (f08bpc) f08rac Computes the CS decomposition of an orthogonal matrix partitioned into four real submatrices f08rnc Computes the CS decomposition of an unitary matrix partitioned into four complex submatrices f11dfc Real sparse nonsymmetric linear system, incomplete $LU$ factorization of local or overlapping diagonal blocks f11dgc Solution of real sparse nonsymmetric linear system, RGMRES, CGS, Bi-CGSTAB or TFQMR method, incomplete $LU$ block diagonal preconditioner computed by nag_sparse_nsym_precon_bdilu (f11dfc) f11dtc Complex, sparse, non-Hermitian linear system, incomplete $LU$ factorization of local or overlapping diagonal blocks f11duc Solution of complex, sparse, non-Hermitian linear system, RGMRES, CGS, Bi-CGSTAB or TFQMR method, incomplete $LU$ block diagonal preconditioner computed by nag_sparse_nherm_precon_bdilu (f11dtc) f12atc Initialization function for nag_complex_banded_eigensystem_solve (f12auc) computing selected eigenvalues and, optionally, eigenvectors of a complex banded (standard or generalized) eigenproblem. f12auc Selected eigenvalues and, optionally, eigenvectors of complex non-Hermitian banded eigenproblem, driver f16eac Dot product of two vectors, allows scaling and accumulation. f16gcc Complex weighted vector addition g01atc Computes univariate summary information: mean, variance, skewness, kurtosis g01auc Combines multiple sets of summary information, for use after nag_summary_stats_onevar (g01atc) g01hdc Computes the probability for the multivariate Student's $t$-distribution g01lbc Computes a vector of values for the probability density function of the multivariate Normal distribution g01wac Computes the mean and standard deviation using a rolling window g02ajc Computes the nearest correlation matrix to a real square matrix, using element-wise weighting g02bzc Combines two sums of squares matrices, for use after nag_sum_sqs (g02buc) g03gac Fits a Gaussian mixture model g05xac Initializes the Brownian bridge generator g05xbc Generate paths for a free or non-free Wiener process using the Brownian bridge algorithm g05xcc Initializes the generator which backs out the increments of sample paths generated by a Brownian bridge algorithm g05xdc Backs out the increments from sample paths generated by a Brownian bridge algorithm g05xec Creates a Brownian bridge construction order out of a set of input times g05zmc Setup for simulating one-dimensional random fields, user-defined variogram g05znc Setup for simulating one-dimensional random fields g05zpc Generates realizations of a one-dimensional random field g05zqc Setup for simulating two-dimensional random fields, user-defined variogram g05zrc Setup for simulating two-dimensional random fields, preset variogram g05zsc Generates realizations of a two-dimensional random field g05ztc Generates realizations of fractional Brownian motion g10bbc Kernel density estimate using Gaussian kernel (thread safe) g13mec Computes the iterated exponential moving average for a univariate inhomogeneous time series g13mfc Computes the iterated exponential moving average for a univariate inhomogeneous time series, intermediate results are also returned g13mgc Computes the exponential moving average for a univariate inhomogeneous time series h05aac Best $n$ subsets of size $p$ (reverse communication) h05abc Best $n$ subsets of size $p$ (direct communication) s22bac Real confluent hypergeometric function ${}_{1}F_{1}\left(a;b;x\right)$ s22bbc Real confluent hypergeometric function ${}_{1}F_{1}\left(a;b;x\right)$ in scaled form s22bec Real Gauss hypergeometric function ${}_{2}F_{1}\left(a,b;c;x\right)$ s22bfc Real Gauss hypergeometric function ${}_{2}F_{1}\left(a,b;c;x\right)$ in scaled form. s30ncc Heston's model option pricing with term structure x07aac Determines whether its argument has a finite value x07abc Determines whether its argument is a NaN (Not A Number) x07bac Creates a signed infinite value. x07bbc Creates a NaN (Not A Number) x07cac Gets current behaviour of floating-point exceptions x07cbc Sets behaviour of floating-point exceptions

## 3  Withdrawn Functions

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

## 4  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 will be withdrawn at Mark 25.
The following functions have been superseded, but will not be withdrawn from the Library until Mark 26 at the earliest.