NAG Toolbox for MATLAB
 Contains essentially all NAG functionality

not a subset
 Available for


Windows and Linux (32/64-bit)
Mac OS X 10.5 (Intel 64 bit)
 Installed under usual MATLAB toolbox directory
 Makes use of a shared version of NAG Library

e.g. DLL on Windows
 Don’t need to have preinstalled the Library
NAG and MATLAB
4
Structure of the Toolbox
 Comprehensive interfaces to NAG Fortran Library
 Fully integrated into MATLAB



Many routine parameters become optional
Easier to read code
Complete documentation for each routine

including examples
 Complementary functionality to MATLAB


Could be an alternative to several specialist toolboxes
We are not trying to compete with MATLAB
NAG and MATLAB
5
A user comments...
“I really like the NAG Toolbox for MATLAB for the
following reasons:
It has saved my employer, The University of
Manchester, a lot of money since we don’t need as
many licenses for toolboxes such as Statistics,
Optimisation, Curve Fitting and Splines.
It can speed up MATLAB calculations – see my article
on MATLAB’s interp1 function for example.
Their support team is superb.”
Mike Croucher, www.walkingrandomly.com
NAG and MATLAB
6
Structure of the Toolbox (1)
 Same as the NAG Library
 Divided into chapters


each devoted to a branch of numerical analysis or statistics
each has a 3-character name and a title


e.g., F03 – Determinants
Exceptionally, Chapters H and S have one-character names
 All Toolbox routines have five-character names

beginning with the characters of the chapter name


e.g., d01aj
Note that the second and third characters are digits, not letters
 e.g., 0 is the digit zero, not the letter O
 Next release will support long names
NAG and MATLAB
7
Structure of the Toolbox (2)
 Documentation same as any NAG Library

each chapter has informative introduction



technical background to field
assistance in choosing appropriate routine
each routine has complete description





description of method and references
specification of parameters and argument list
explanation of error exit
remarks on accuracy
working example showing how to call routine
 many of these have been enhanced in Mark 23
NAG and MATLAB
8
Structure of the Toolbox (3)
 Demos included at Mark 22 of the Toolbox
 Available through the MATLAB help system

PDF versions of documents available


click on the links at the top of each page
or access them via the NAG website
NAG and MATLAB
9
NAG Toolbox help
chapters
MATLAB formatting
NAG formatting
(in PDF)
How to call the
NAG routine
Calling the routine
in MATLAB
MATLAB plot
Example (1)
 Plot Bessel function of first kind

use NAG routine s17ae
x = 0.5:0.25:20;
for i=1:length(x)
y(i) = s17ae(x(i));
end
plot(x,y);
1
0.5
0
-0.5
0
2
NAG and MATLAB
4
6
8
10
12
14
16
18
12
20
Example (2): Solve
Ax  b
 1.80 2.88 2.05  0.89 
 5.25  2.95  0.95  3.80 

A
 1.58  2.69  2.90  1.04 
  1.11  0.66  0.59 0.08 


 9.52 
 24.35 

b
 0.77 
  6.22 


NAG and MATLAB
13
Example contd.
 NAG routine f07aa

solves a real system of linear equations
a = [ 1.80, 2.88, 2.05, -0.89;
5.25, -2.95, -0.95, -3.80;
1.58, -2.69, -2.90, -1.04;
-1.11, -0.66, -0.59, 0.80];
b = [ 9.52;
24.35;
0.77;
-6.22];
[aOut, ipiv, bOut, info] = f07aa(a, b);
NAG and MATLAB
14
Example contd.
 Solution is returned in bOut vector:
bOut
bOut =
1.0000
-1.0000
3.0000
-5.0000
NAG and MATLAB
15
Input/output parameters
 In the Fortran Library a parameter can serve both
as input & output [it is overwritten at output]:
F07AAF(N, NRHS, A, LDA, IPIV, B, LDB, INFO)
 In MATLAB, params are split into input and output:
[aOut, ipiv, bOut, info] = f07aa(a, b);
NAG and MATLAB
16
Input/output parameters
 Why are there different parameters?
F07AAF(N, NRHS, A, LDA, IPIV, B, LDB, INFO)
[aOut, ipiv, bOut, info] = f07aa(a, b);
 Some parameters are determined at runtime:



dimensions of arrays
workspaces
parameters that depend entirely on other input parameters
 Some parameters are optional…
NAG and MATLAB
17
Optional Parameters
 Provided after all compulsory parameters
 Appear in pairs

a string representing the name followed by the value
 Pairs can be provided in any order
 Examples of use of optional parameters:

A sensible default value exists



which applies to many problems
The parameter only applies to some cases
Value of the parameter can normally be determined

from that of other parameters at runtime
NAG and MATLAB
18
Optional Parameters - example
 In the system of equations above

it is obvious that the size of the matrix A, n, is 4
 But we can tell the NAG routine that n is 3

in which case it will solve the system represented by the
top-left 3x3 section of A, and the first three elements of b
 Here’s how we do that…
NAG and MATLAB
19
Optional Parameters - example
[aOut, ipiv, bOut, info] = f07aa(a, b, 'n', int32(3));
bOut
bOut =
4.1631
-2.1249
3.9737
-6.2200
 Last element of bOut can (& should) be ignored


b is a 4x1 matrix on input & output
even though its last element is not being used
NAG and MATLAB
20
Another option
 A similar outcome can be achieved by:
[aOut, ipiv, bOut, info] = f07aa(a(1:3,1:3), b(1:3));
bOut
bOut =
4.1631
-2.1249
3.9737
 Here bOut is of appropriate size
NAG and MATLAB
21
Another Example – Overriding Defaults
 g01hb computes probabilities associated with a
multivariate distribution to a tolerance whose value
defaults to 0.0001:
g01hb(tail, a, b, xmu, sig)
ans =
0.9142
 We can specify a non-default value for tol:
g01hb(tail, a, b, xmu, sig, 'tol', 0.1)
ans =
0.9182
NAG and MATLAB
22
Providing m-files as parameters (1)
 Some NAG routines expect an m-file parameter


to evaluate a function
e.g. integrand, objective function, etc
 Here’s an example
d01ah(0, 1, 1e-5, 'd01ah_f', int32(0))
ans =
3.1416
 where d01ah_f.m is a file containing
function [result] = d01ah_f(x)
result = 4.0/(1.0+x^2);
NAG and MATLAB
23
Providing m-files as parameters (2)
 Examples are provided for every NAG routine

including those that have m-file parameters
 Function handles can also be used in MB23


when the argument is an existing MATLAB command
or a simple expression returning one value


which can be represented as an anonymous function
when the argument is a function that is local to an m-file.
 So in MB23 we could have, for example:
nag_quad_1d_fin_well(0, pi, 1e-5, @sin, nag_int(0))
NAG and MATLAB
24
MATLAB types (1)
 Need to use the correct types when calling Toolbox


MATLAB assumes by default that every number is a double
so users need to covert their data to the appropriate type


int32(1) - to create an a 4-byte integer, value 1


can check range of supported values with intmin & intmax
 intmax(‘int8’) = 127
 intmin(‘int32’) = -2147483648
complex(1,1) - to create 1.0000 + 1.0000i


if it is an integer, a complex number or a logical
can check variable with isreal function
logical(0) - to create a logical that is .FALSE.
NAG and MATLAB
25
MATLAB types (2)
 MATLAB sparse arrays not supported in Toolbox

need to use full storage

myArray = full(mySparseArray)
 Toolbox on 32bit machines uses 32bit integers



hence int32(3) cast in call to f07aa
uses 64bit integers on 64bit machines
next release uses nag_int() function

more portable
 Using an incorrect type throws a NAG:typeError :
s01ea(0)
??? argument number 1 is not a complex scalar
of class double.
NAG and MATLAB
26
When things go wrong
 The NAG routines can throw a number of errors:








NAG:licenceError - A valid licence couldn’t be found
NAG:arrayBoundError - Array provided is too small
NAG:callBackError - An error occurred when executing an
M-File passed as a parameter to the routine
NAG:missingInputParameters
NAG:optionalParameterError - Not in name/value pairs, or
the name provided is not an optional parameter
NAG:tooManyOutputParameters
NAG:typeError - A parameter is of the wrong type
NAG:valueError - An incorrect value has been provided for
a parameter
NAG and MATLAB
27
Errors and Warnings
 Usually, the error message gives more details
 E.g., a NAG:arrayBoundError might display:
??? The dimension of parameter 2 (A)
should be at least 4
 Warnings can be disabled:
warning('off', 'NAG:warning')
but it’s vital to check the value of ifail on exit
NAG and MATLAB
28
NAG routines and ifail
 Each NAG routine has an ifail parameter

or info in the case of f07 and f08 routines
 Non-zero value on exit indicates nature of error


depends on the routine
documentation has full details

see, e.g. d02bg
NAG and MATLAB
29
User Workspace – why?
 Many routines have parameters for user workspace


passed unchanged to user-supplied functions or subroutines
allows data to be passed to subprograms in a thread-safe way
 Typically there are two or three such parameters

an integer and real array and, sometimes, a character array
 MATLAB toolbox replaces these by a single object

provides more flexibility
NAG and MATLAB
30
User Workspace - Cell Arrays
 Provides a way to collect arrays into a single datatype


cell array contains indexed data containers called cells
each cell can contain any type of data

including arrays, each of which can have any size and type
 Use the curly braces as a constructor:
>>C = {1:3, pi; magic(2), ‘A string’}
C =
[1x3 double]
[ 3.1416]
[2x2 double]
‘A string’
 Use curly braces when displaying cell contents:
>>C{2,1}(1,1)
 Display contents of whole cell with celldisp
NAG and MATLAB
31
User Workspace - example
 Here, “user” is a cell array with three arrays:
x = [0.5; 1; 1.5];
y = [0.14,0.18,0.22, < snip >
t = [[1.0, 15.0, 1.0],
< snip >
[15.0, 1.0, 1.0]];
2.10,4.39];
user = {y, t, 3};
[xOut, fsumsq] = e04fy(int32(15), 'e04fy_lsfun1', ...
x, 'iuser', user);
 The data is then passed on to e04fy_lsfun1.m
NAG and MATLAB
32
Comparisons
 We look at a selection of Toolbox chapters:



Numerical Linear Algebra
Interpolation
Local and Global Optimization
NAG and MATLAB
35
Numerical Linear Algebra
 Dense linear algebra routines in MATLAB use LAPACK

although not all of LAPACK is used
 The NAG Library implements the whole of LAPACK
 E.g. to compute a subset of eigenvalues
NAG and MATLAB
39
Eigenvalues and Vectors – Chapter F08
 We compare:
 The MATLAB function eig
[v,d] = eig(a);
 f08fa (DSYEV in LAPACK). QR algorithm like eig
[a, w, info] = f08fa('V', 'U', a)
 f08fc (DSYEVD), divide and conquer algorithm
[a, w, info] = f08fc('V', 'U', a)
NAG and MATLAB
40
Eigenvalues and Eigenvectors
 Timings
(eig 130 secs
for n=3000
on one core)
NAG and MATLAB
41
Eigenvalues and Eigenvectors
 Speedup
NAG and MATLAB
42
Subset of Eigenvalues and Eigenvectors
 What about a subset of eigenvalues?
 Not possible with eig, but the Toolbox can
 Use the “expert” drivers in LAPACK via the Toolbox

For example, the first 10%:
[a, m, w, z, isuppz, info] = ...
f08fd('V','I', 'U', a, 1.0, 1.0, ...
int32(1), int32(n/10), -1)
NAG and MATLAB
43
Subset of Eigenvalues and Eigenvectors
 Speedup
NAG and MATLAB
44
Curve fitting
 Finding a function which
approximates a data set
 Data typically contains
random errors (e.g. from
experiment)
 Smoothness of fit likely
to be important
 Core MATLAB doesn’t have a nice basic curve
fitting function
NAG and MATLAB
45
MATLAB Curve Fitting
 MATLAB uses only polynomial fitting
with polyfit. Suppose the data:
xi , y 
m
i i 1
has distinct xi values, and we wish to find a polynomial p
of degree at most n such that:
p( x )  y
i
i
 The polyfit function computes
the least squares (only)
polynomial fit, that is, it
determines p that minimizes:
NAG and MATLAB
m
 ( p( x )  y )
i 1
i
2
i
46
NAG Curve Fitting - Chapter E02
 The NAG curve fitting chapter allows:

different fits, including L1 (minimizes sum of errors) and
mini-max (minimizes the maximum error)
curve fitting via polynomials and cubic splines
surface fitting via bivariate polynomials & bicubic splines:

Other functionality includes:






General Linear and Nonlinear Fitting Functions
Constrained Problems
Padé Approximants
weighting of data
NAG and MATLAB
47
Interpolation
 Interpolation is about fitting the data points exactly
 Matlab has



interp1 – included linear and bicubic spline fits in 2D
griddata – Delaunay triangulation of the data (mainly), 3D
interp2 – 3D interpolation, including bicubic splines
 More advanced fits available in Curve Fitting Toolbox
 NAG Interpolation chapter is E01


Methods of finding and computing functions in 1, 2 & 3D
Polynomials, splines, Shepard’s method etc.
NAG and MATLAB
48
Interpolation
 Case study from the University of Manchester
 Student wanted to interpolate data on a fine grid
between x=0 and x=1 using piecewise cubic Hermite
interpolation.
 Originally used MATLAB’s interp1 function:
t=0:0.00005:1;
y1 = interp1(x,y,t,'pchip');
 Replaced with:
[d,ifail] = e01be(x,y);
[y2, ifail] = e01bf(x,y,d,t);
% compute interpolant
% evaluate interpolant
 Speed up of 17 times original. Complete code now
runs in 26 minutes versus 70 minutes.
NAG and MATLAB
49
Optimization
 Core MATLAB has:
 Unconstrained optimization, so can’t do ...
NAG and MATLAB
50
Linearly constrained optimization
NAG and MATLAB
51
5
Optimization - Nonlinear Constraints
NAG and MATLAB
52
52
5
NAG Optimization - Chapter E04
 Categorize problem via objective function




linear
nonlinear
sum of squares of nonlinear functions
quadratic
 Important to choose appropriate method


for problem type
for efficiency and best chance of success
NAG and MATLAB
53
Nonlinear problem example
 Minimise
F ( x1 , x2 )  (1  x1 )  100( x2  x )
2
2 2
1
 This F is called Rosenbrock’s function


good test for optimisers
minimum is
F (1,1)  0
NAG and MATLAB
54
Rosenbrock’s function
NAG and MATLAB
55
Optimization: e04uc vs fmincon
 A problem from a European bank customer




48 variables
9 linear constraints
No nonlinear constraints
No derivatives supplied
 fmincon required 1890 evaluations, took 87.6 sec
 e04uc required 1129 evaluations, took 49.4 sec
NAG and MATLAB
57
Local optimization
NAG and MATLAB
58
NAG Global Optimization
 Pre Mark 22 routines were for local optimization

No guarantee about which minimum was returned
 Users often ask for global optimization methods
 NAG now has routines based on the 'multilevel
coordinate search' method of Huyer and Neumaier
http://www.nag.co.uk/numeric/FL/nagdoc_fl22/xhtml/E05/e05intro.xml
 ‘Particle Swarm’ has just arrived at Mark 23
NAG and MATLAB
59
The search space is
split into sub-boxes.
Eventually local
searches are
performed.
6
The branching-style
algorithm keeps track
of boxes that contain
the best minimum so
far, and others that are
yet to be explored fully
6
A global minimum is
found in 158 function
evaluations
6
Conclusions
 MATLAB is clearly a very powerful piece of software

data generation, post processing, ease of use.
 MATLAB has a huge range of mathematical functions

but much of its functionality is provided by toolboxes

need to be purchased separately.
 The NAG Toolbox for MATLAB



provides a large choice of algorithms
extends the basic MATLAB functionalities
can enhance performance
NAG and MATLAB
68