Guide to the NAG Library Documentation
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 and the NAG AD Library.
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.
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 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 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:
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:
||Arguments (see Section 4)
||Error Indicators and Warnings
||Parallelism and Performance
||Example (see Section 2.6 in the Introduction to the NAG Library FL Interface)
In some documents (notably Chapters E04
) there are a further three sections:
||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.
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.
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++.
- 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.
- 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.
Note that for some interfaces (for example, in NAG Library for Python) the abbreviated names correspond to the methods available within a class whose name corresponds to the omitted chapter name. For routines that correspond to routines from the LAPACK or BLAS libraries, the abbreviated long style name is the corresponding LAPACK or BLAS library name and that name may be used directly.
- In the Full style the fully prefixed name such as nagf_opt_handle_init is used in almost all cases. (The abbreviated form is used in some contexts such as decision trees and titles, for reasons of space.)
The CL Interface routine document Specification section (Section 2) is always shown in the same form, however the FL and AD interface routine document Specifications may be shown in multiple formats. By default F90 and C are shown in FL, while the F90 and C++ specifications are shown in AD.
- the ‘Natural’ Fortran declaration.
- C header interface. Note the AD Library documentation uses C++ syntax, treating the C and C++ options as equivalent.
- C++ interface, the most notable difference to the C being that scalars passed by reference are declared as & rather than *.
As noted in the previous section, Section 5
, this documentation offers some viewing choices that, by default, are saved in cookies
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
and changing the line
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 and AD interfaces to the same routine, c05ayc
A Keyword Search box is also provided for quick searching of a known routine or keyword (see Section 8
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.
||External link to a URL that is not part of this documentation.
||chap, chapint, genint
||Linking to a Chapter Contents, Chapter Introduction and general introduction documentation
||sec, dtree, ref, eqn, verbatim, fig, item, note, table
||Linking to a section or item within this documention.
||Linking to an IFAIL value
||Linking to an argument name
||Linking to a member of a C structure
||Linking to an optional parameter or an optional parameter value
||Linking to a NAG type
||Linking to a deprecated routine document
||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.)
- 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.)
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/
) 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/installation.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.
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. NAG no longer distributes the NAG Library Manual in PDF format.
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.