Guide to the NAG Library Documentation
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:
- to give background information about different areas of numerical and statistical computation;
- to advise on the choice of the most suitable NAG Library routine or routines to solve a particular problem;
- to give all the information needed to call a NAG Library routine correctly using the required interface, and to assess the results.
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:
-
(a)select an appropriate chapter or routine by using the online Keyword and GAMS Search facility;
-
(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;
-
(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);
-
(d)read the Users' Note for your implementation (this contains instructions on how to compile and run a program);
-
(e)consult local documentation, which should be provided by your local support staff, about access to the Library on your computing system;
-
(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:
- Chapter Contents, e.g., Chapter D01 (Quad) Contents;
- Chapter Introduction, e.g., the D01 Chapter Introduction;
- Routine Documents, one for each documented routine in the chapter.
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.
- In the CPP Interface documentation four styles are offered.
NAG is the traditional NAG naming scheme and Short, Long and Full use the standard C++ prefixed names based on the NAG long name, but using the :: separator. Showing or not showing the namespace prefixes according to the option.
- In the documentation for the other interfaces, the Short option selects the NAG name, and Full shows the fully prefixed long name, with the Long option showing the name with prefixes removed, so for example e04raf would be shown as nagf_opt_handle_init with the Full option and as handle_init with the Long option. Note that the abbreviated long name, handle_init, is for documentation purposes only, and (unlike the case in the CPP Interface) cannot be used directly in code.
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
7
Navigating the Documentation
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 |
8
Keyword Search
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.)
- An asterisk (*) acts as a wildcard; so gauss-* matches gauss-kronrod, gauss-newton, etc.
- Special keywords prefixed by = may be used to limit the results to a specific interface, for example adding =fl will restrict results to the FL Interface.
- Indexed keywords include the GAMS classification scheme. For example, g2e corresponding to the GAMS hierarchy: G = optimization; G2 = constrained; G2e = quadratic programming.
- Each routine in a search result lists the routine name, a short description of the routine, names, keywords, and associated GAMS classification names; hovering over each of the classification names reveals its full GAMS definition.
- Routine names are indexed by long and short names, and, where applicable, BLAS and LAPACK names. For example, the keyword dgesv returns, among other details, the names f07aaf, nagf_lapacklin_dgesv and dgesv.
- A search URL ending in a query such as ?q=real+eigenvalue will return the search page with the search box initialized with real eigenvalue and return the results. You can update the URL of the current page to reflect the current search by clicking the 'Update URL' button above the search box. (This may be useful for example to save a search to send via email.)
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.