Guide to the NAG Library Documentation

Settings help

FL Name Style:


1 Introduction

The NAG Library Manual is the principal documentation for the NAG Library. The Library Manual provides you with information to support the use of the NAG FL Interface, the NAG CL Interface, the NAG CPP Interface and the NAG AD Library.

2 Using the Manual

The Manual is designed to serve the following functions for the NAG Library:
At the beginning of the Manual are a number of general introductory documents:
There is full documentation for each of the available interfaces for the NAG Library.
FL Interface Replacement Calls Advice and CL Interface Replacement Calls Advice provide advice on how to modify your program for those cases where a routine has been withdrawn or deprecated.
Known Issues lists for the Library FL Interface and CL Interface are also available on the NAG website providing workarounds and advice for the versions of the Library affected.
Finally there are documents providing details of:
In the key functionality field of Optimization, an index, for each of the NAG FL Interface and NAG CL Interface, and spanning several chapters, has been provided to give you some guidance on the appropriate choice of routine:
In addition, the documentation includes a Keyword and GAMS Search which is available as a Keyword Search box at the top of every page see Section 8.
It is recommended that all users, both familiar or unfamiliar with this Library, who are thinking of using a routine from it, read the Introduction to the NAG Library Interface that you are planning to use (Introduction to the NAG Library FL Interface, Introduction to the NAG Library CL Interface, Introduction to the NAG Library CPP Interface and Introduction to the NAG AD Library). The NAG FL Interface and NAG CL Interface documents provide you with interface specific advice on the NAG Library documentation, programming advice, error handling, use of long names, input/output, auxiliary routines, error handling, structure of error messages, dynamic memory allocation, licence management, unexpected error, legacy error handling, and calling the Library from other languages. The NAG CPP Interface describes the new Experimental C++ Interfaces, which are provided for a small subset of the Library to get feedback on the design. The AD Library document provides additional advice specific to using NAG AD Library Interfaces.
When choosing a routine you are recommended to take to the following steps:
  1. (a)select an appropriate chapter or routine by using the online Keyword and GAMS Search facility;
  2. (b)read the relevant Chapter Introduction which gives background information about that area of numerical computation, and recommendations on the choice of a routine, including indexes, tables and decision trees;
  3. (c)choose a routine, and read the routine document. Each routine document is essentially self-contained (it may, however, contain references to related documents). It includes a description of the method, detailed specifications of each argument, explanations of each error exit, remarks on accuracy, and (in most cases) an example program to illustrate the use of the routine. In some cases a plot accompanies an example program to illustrate the results from running the example program (possibly amended from the original to output more data points). If it transpires that the routine does not meet your needs, return to step (a);
  4. (d)read the Users' Note for your implementation (this contains instructions on how to compile and run a program);
  5. (e)consult local documentation, which should be provided by your local support staff, about access to the Library on your computing system;
  6. (f)obtain a copy of the example program (see Section 2.6 in the Introduction to the NAG Library FL Interface or Section 2.3 in the Introduction to the NAG Library CL Interface) for the particular routine of interest and experiment with it.
You should now be in a position to include a call to the routine in a program, and to attempt to compile and run it.
It is useful to keep up to date with the following documents as they are subject to change:

3 Structure of the Documentation

The NAG Library Manual is the principal documentation for the NAG Library. It has the same structure as the Library. Just as the Library contains sets of generic interfaces (FL, CL and AD) separated into chapters of routines, so does the manual contain, for each such interface set, a collection of general introductory documents, followed by a set of chapters listed in alphanumeric order. Each chapter consists of the following documents:
A routine document has the same long or short name as the routine which it describes. Within each chapter, routine documents occur in alphanumeric order by long or short names depending on the chosen documentation Name Style setting (see Section 5.1). For those chapters that have both ‘a’ and ‘f’ versions of a routine, the routine descriptions are combined into one routine document.
All routine documents have the same structure consisting of ten numbered sections:
1. Purpose
2. Specification
3. Description
4. References
5. Arguments (see Section 4)
6. Error Indicators and Warnings
7. Accuracy
8. Parallelism and Performance
9. Further Comments
10. Example (see Section 2.6 in the Introduction to the NAG Library FL Interface)
In some documents (notably Chapters E04, E05 and H) there are a further three sections:
11. Algorithmic Details
12. Optional Parameters
13. Description of Monitoring Information
The sections numbered 11. and 13. above are optional; thus, the section titled Optional Parameters may appear as (the possibly final) Section 11.

4 Specification of Arguments

The specification of arguments is slightly different dependent on the interface that you are using but are consistently presented as Section 5 of each routine document in the order of their appearance in the argument list.
See the Introduction to the NAG Library FL Interface, Introduction to the NAG Library CL Interface and the Introduction to the NAG AD Library for interface specific details of classification of arguments, constraints and suggested values, and array arguments.

5 Personalisation of Documentation Settings

The NAG Library provides routines in two name styles, and is also callable from multiple languages. The documentation allows you to customise settings to tailor documents to a given name style and language interface(s). Unless ‘Cookies’ have been disabled, these choices will be preserved between pages as you navigate the manual.
On each page there is a Show settings button which opens a dialog that lets you choose the name style to use for chapters and routines, and to choose up to three languages to be used in the Specification section of routine documents.
As an alternative to using the settings dialog, the settings may be initialized by using options specified in the URL to the documentation, for example: links to the table of contents with chapters ordered by their long names, and (if cookies are enabled) routine documents linked from the table of contents will show the specification in Fortran and C++.

5.1 Name Style

Short This is the traditional NAG naming convention, see Section 3.2.1 in How to Use the NAG Library.
For example, the E04 chapter of the NAG FL Interface, containing routines for local optimization problems, will list routine short names such as e04raf.
Long NAG also makes the routines available under longer, more readable, names (usually via Fortran module declarations, C header files or similar mechanisms in the appropriate language). See Section 3.2.2 in How to Use the NAG Library for details.
All routine long names in a chapter share a common prefix so, within the context of a chapter, the long documentation option normally omits this prefix. The full long name of a routine is used elsewhere and also within the context of its own chapter when used in code fragments (to be syntactically valid) or where it is clearer to do so.
For example, the E04 chapter of the NAG CL Interface contains routines with long names that share the prefix nag_opt, including nag_opt_handle_init (short name e04rac); within the context of the chapter, the documentation will refer to handle_init when using the long option.
The settings menu allows some customisation of the naming style used in the documentation.
The menu options are not followed in all contexts. For example specification sections always use a form of the name usable in code, and so show the Full form even if the abbreviated form is being used elsewhere in the document. Conversely, for reasons of space, the abbreviated form is used in some contexts such as decision trees and titles even if the Full option is being used.

5.2 Specification Language

The CL and CPP Interface Specification sections (Section 2) always show the specifications in the same form (using C and C++ respectively). However, the FL Interface and AD Library specifications may be shown in multiple formats.
Fortran the ‘natural’ Fortran declaration.
C the C header declaration. Note this is not the CL Interface.
C++ the C++ declaration. Note this is not the CPP Interface.
By default Fortran and C specifications are shown in the FL Interface, while the Fortran and C++ specifications are shown in the AD Library.

6 Cookies

As noted in the previous section, Section 5, this documentation offers some viewing choices that, by default, are saved in cookies; data saved by your browser. These settings are stored in your browser and are not transmitted to NAG or other sites that may be hosting copies of this documentation, however there are privacy issues surrounding the use of cookies and this notice fulfils a legal requirement to notify readers that cookies are being used.
If you are reading a local copy of this documentation, cookies are not set unless you use the settings menu as described in Section 5.
If you are hosting a copy of this documentation, you may disable the use of cookies for that copy by modifying the file ../../styles/nagmathml.js and changing the line
var nagusecookies = 1 // set to anything else to stop use of cookies
to
var nagusecookies = 0 // set to 1 to enable cookies and set to anything else to stop use of cookies
Each page of the NAG Library Manual includes a table of contents, which is in the left hand column on typical display screens and at the top of the page on smaller screens. The table of contents provides links to sections in the current document and also to the relevant chapter introduction and table of contents. Also, where appropriate, it provides links between the relevant interfaces, so for example the FL interface documentation of c05ayf has links to the CL, CPP and AD interfaces to the same routine, c05ayc, c05ay and c05ay_a1w_f respectively.
A Keyword Search box is also provided for quick searching of a known routine or keyword (see Section 8 for guidelines).
Each library document contains a number of hyperlinks to particular elements, e.g., arguments, sections, chapter contents, etc. The following key identifies the colour used for each element. These colours are set in the first few lines of the file styles/libdoc.css. If you have installed a local copy of the documentation then you may change the colours for reasons of accessibility or personal preference.
Colour CSS classes Link Type
pale blue url External link to a URL that is not part of this documentation.
green chap, chapint, genint Linking to a Chapter Contents, Chapter Introduction and general introduction documentation
light green sec, dtree, ref, eqn, verbatim, fig, item, note, table Linking to a section or item within this documention.
navy blue ifail Linking to an IFAIL value
red arg Linking to an argument name
pink member Linking to a member of a C structure
purple optparam, optval Linking to an optional parameter or an optional parameter value
brown nagtype Linking to a NAG type
grey wdrn Linking to a deprecated routine document
royal blue htmltoc, rout, tocexample, plot Linking in a table of contents, Links to routine document, Example, or an Example Plot
Most pages in the Library documentation include a search text box that allows the documentation to be searched for a list of keywords, with results being returned in the page Keyword and GAMS Search.
You may include keywords, GAMS classification codes and names of routines, using the TAB, arrow keys or the mouse to complete words from the drop-down menu. Multiple keywords must be separated by a space character.
The ENTER key will return a list of related routines; further keywords may be added, separated with white space, and ENTER re-pressed to refine the search list.
Keywords are restricted to lowercase ASCII letters, digits, ', - and _. For example, to search for Padé, use pade. (Search results show keywords with richer formatting.)

9 Viewing HTML Files

NAG HTML files do not use any proprietary browser specific features, and conform to relevant W3C Recommendations (HTML, MathML, SVG, CSS).
The documentation should work in any reasonably current web browser. If you require information for additional browsers please contact NAG Technical Support.
For Firefox and other Mozilla based browsers, which render the mathematics natively, you may wish to install additional math fonts as described in the Mozilla documentation at https://www.mozilla.org/projects/mathml/fonts/.
If Firefox is not being used, then the JavaScript on the page loads the MathJax JavaScript library (https://www.mathjax.org) to enable MathML rendering. By default this is loaded from the web using the cloudflare Content Distribution Network. If you require the documentation to work without an Internet connection then you may either use Firefox as described in the previous paragraph or you may download a local copy of MathJax (https://docs.mathjax.org/en/latest/web/hosting.html) which needs to be unpacked on to your local fileserver or file system, and then edit the file ../../styles/nagmathml.js changing the line cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0 to refer to your local installation.

10 Printing the Documentation, and Producing PDF

It is possible to print your HTML files from the browser, on most systems the same print drivers may be used to save a PDF version of the document if this is required.
Support for printing from browsers, especially support for printing mathematics, varies considerably between versions of browsers, and the Operating System and printer drivers in use. In case of difficulty, please contact the NAG Technical Support Service who should be able to advise on any known issues on using the NAG documentation with common browsers.