NAG Toolbox

The Design of The NAG Toolbox for MATLAB

The first section of this document describes the structure of the Toolbox and its documentation, and should be of interest to all users. The second part, Comparison with the Fortran Library, is mainly of interest to users familiar with using NAG routines directly.

Structure of the Toolbox

The Toolbox has the same structure as the NAG Library. The Library is divided into chapters, each devoted to a branch of numerical analysis or statistics. Each chapter has a three-character name and a title, e.g., Exceptionally, Chapters H and S have one-character names. (The chapters and their names are based on the ACM modified SHARE classification index (see ACM (1960–1976)).)

All documented routines in the Toolbox have five-character names, beginning with the characters of the chapter name, e.g.,

Note that the second and third characters are digits, not letters; e.g., 0 is the digit zero, not the letter O.

The documentation of the Toolbox follows the same chapter structure as the Library, so each chapter of routines has a corresponding chapter in the documentation, consisting of the following documents:

All documentation is available through the MATLAB help system, however some documents contains a great deal of mathematical equations, which the MATLAB help system is not always able to display clearly. As an alternative it is possible to consult PDF versions of the documents by clicking on the links at the top of each page, or accessing them via the NAG website.

Comparison with the Fortran Library

This section will mainly be of interest to users familiar with using the NAG Library directly from Fortran or another high-level programming environment. It explains the rationale for deciding whether a parameter is optional or omitted from the interface completely, and other differences between the Library and the Toolbox.

Optional Parameters

Optional parameters fall into one of the following categories:
  1. A sensible default value exists which applies to many problems.
  2. The parameter only applies to some cases which the routine is designed to solve.
  3. The value of the parameter can normally be determined from that of other parameters at runtime.

Parameters Omitted from the Toolbox Interface

The following kinds of parameters have been omitted completely from the toolbox interface, because they can always be determined at runtime:
  1. Dimensions of arrays.
  2. Workspace whose size depends entirely on the problem data.
  3. Parameters whose value depends entirely on that of other input data.

User Workspace

Many routines have parameters for user workspace, which are passed unchanged to user-supplied functions or subroutines. This allows data to be passed to these subprograms in a thread-safe way. Typically there are two or three such parameters, an integer and real array and, sometimes, a character array. In the MATLAB toolbox these are replaced by a single MATLAB object, to provide more flexibility. For example in the following case user is a cell array containing three pieces of data:
x = [0.5; 1; 1.5];
y =
[0.14,0.18,0.22,0.25,0.29,0.32,0.35,0.39,0.37,0.58,0.73,0.96,1.34,2.10,4.39];
t = [[1.0, 15.0, 1.0],
     [2.0, 14.0, 2.0],
     [3.0, 13.0, 3.0],
     [4.0, 12.0, 4.0],
     [5.0, 11.0, 5.0],
     [6.0, 10.0, 6.0],
     [7.0, 9.0, 7.0],
     [8.0, 8.0, 8.0],
     [9.0, 7.0, 7.0],
     [10.0, 6.0, 6.0],
     [11.0, 5.0, 5.0],
     [12.0, 4.0, 4.0],
     [13.0, 3.0, 3.0],
     [14.0, 2.0, 2.0],
     [15.0, 1.0, 1.0]];
user = {y, t, 3};

[xOut, fsumsq] = e04fy(int32(15), 'e04fy_lsfun1', x, 'iuser', user);
It is used in the M-File e04fy_lsfun1.m as follows:
function [fvecc, user] = lsfun1(m, n, xc, user)
  fvecc=zeros(m,1);

  % y is in user{1} and t is in user{2}
  for i = 1:m
    fvecc(i) = xc(1) + user{2}(i,1)/(xc(2)*user{2}(i,2)+xc(3)*user{2}(i,3))-...
                user{1}(i);
  end

Input/Output Parameters

In the Fortran Library it is common for parameters to have their values over-written on exit from the routine. These routines are marked as Input/Output in the documentation. Since this behaviour seems unnatural in MATLAB, we have chosen to split parameters into Input and Output only.

Routines Omitted from the Toolbox

The Toolbox contains interfaces to all the routines in Mark 21 of the NAG Fortran Library apart from chapter F06 (Linear Algebra Support Routines) and:
e04djf Supply optional parameter values for e04dgf/e04dga from external file
e04mgf Supply optional parameter values for e04mff/e04mfa from external file
e04mzf Converts MPSX data file defining LP or QP problem to format required by e04nqf
e04ndf Supply optional parameter values for e04ncf/e04nca from external file
e04ngf Supply optional parameter values for e04nff/e04nfa from external file
e04nlf Supply optional parameter values for e04nkf/e04nka from external file
e04nrf Supply optional parameter values for e04nqf from external file
e04udf Supply optional parameter values for e04ucf/e04uca or e04uff/e04ufa from external file
e04uhf Supply optional parameter values for e04ugf/e04uga from external file
e04uqf Supply optional parameter values for e04usf/e04usa from external file
e04vkf Supply optional parameter values for e04vhf from external file
e04wef Supply optional parameter values for e04wdf from external file
e05jcf Supply optional parameter values for e05jbf from external file
h02bff Interpret MPSX data file defining IP or LP problem, optimize and print solution
h02buf Convert MPSX data file defining IP or LP problem to format required by h02bbf or e04mff/e04mfa
h02ccf Read optional parameter values for h02cbf from external file
h02cff Read optional parameter values for h02cef from external file
p01abf Return value of error indicator/terminate with error message
In addition, in cases where there is a thread-safe and a thread-unsafe variant of a routine (e.g. e04ufa and e04uff) we only provide an interface to the thread safe version.

References

ACM (1960–1976) Collected algorithms from ACM index by subject to algorithms