# Guide to the NAG Library Documentation

Settings help

FL Name Style:

## 1Introduction

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.

## 2Using 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, 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 (New at Mark 27.1) 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);
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:

## 3Structure 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.

## 4Specification 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.

## 5Personalisation 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.1Name 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. 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.2Specification 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. the C header declaration. Note this is not the CL Interface. 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.

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
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.
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
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.)

## 9Viewing HTML Files

NAG HTML files do not use any proprietary browser specific features, and conform to relevant W3C Recommendations (HTML, MathML, SVG, CSS).