# NAG CPP InterfaceIntroduction

Settings help

CPP Name Style:

## 1Introduction

The NAG CPP Interface is a set of C++ interfaces for the NAG Library, supplied as a series of header files. The supplied material is laid out as follows:
Prior to using the NAG CPP Interface you will need to have a version of Mark 28.3 of the NAG Library installed.
When using the interfaces supplied via the NAG CPP Interface you will need to add the include subdirectory to the list of directories your compiler searches for header files, in addition to using any compiler flags usually required by the NAG Library.

## 2The NAG Library Documentation

The Guide to the NAG Library Documentation provides general information on how to use the NAG Library documentation; the following sections are specific to the NAG CPP Interface.

### 2.1Function Documentation

#### 2.1.1Classification of Arguments (Intents)

Arguments are classified as follows.
• input: unless stated otherwise in the individual function documentation, you must assign values to these arguments on or before calling the function, and these values are unchanged on exit from the function.
• output: you need not assign values to these arguments before calling the function; unless stated otherwise in the individual function documentation the function will assign values to them on exit. If possible the function will allocate array arguments to the correct size (see Section 2.1.3).
• input/output: unless stated otherwise in the individual function documentation, you must assign values to these arguments before calling the function, and the function may then change these values. For array arguments where the individual function documentation indicates that no values must be supplied on entry but that values are returned on exit, the function will attempt to allocate the argument to the correct size (see Section 2.1.3).
• Function: unless stated otherwise in the individual function documentation you must supply a callback function (e.g., to evaluate an integrand or to print intermediate output). The prototype for the callback function is given in the individual function documentation and includes full details of its argument list and specifications of its arguments (all enclosed in a box). The arguments of a callback function are classified in a similar manner to above but, because you must write the function rather than call it, the significance of the classification is different.
• input: unless stated otherwise in the individual function documentation, values will be supplied on entry, which your function must not change.
• output: unless stated otherwise in the individual function documentation, you must assign values to these arguments before returning from your function.
• input/output: unless stated otherwise in the individual function documentation, values will be supplied on entry, and you must assign values to them before returning from your function.
In cases where an argument is not referenced or, in the case of callback functions, where a default function has been supplied by NAG you should pass nullptr as the corresponding argument. See Section 10 in handle_​solve_​ipopt for an example where a callback function is not referenced, Section 10 in handle_​solve_​lp_​ipm for an example where a default callback function is used and Section 10 in lars for an example where an input argument is set to nullptr.

#### 2.1.2Constraints

The word ‘Constraint:’ or ‘Constraints:’ in the specification of an input argument introduces a statement of the range of valid values for that argument, e.g.,
• Constraint: $\mathbf{n}>0$.
If the function is called with an invalid value for the argument (e.g., $\mathbf{n}=0$), the function will raise an error (see Section 5).
Constraints on string arguments only list upper case characters, e.g.,
• Constraint: $\mathbf{check}=\text{'N'}$.
In practice, all functions with string arguments are case insensitive.

#### 2.1.3Array Arguments

The actual variable passed as an array argument to the function is referred to as a data container in this documentation.
The interfaces supplied with the NAG CPP Interface support a number of data containers (see Section 3 for details), as such all array arguments are templated and this is shown within the documented function prototype. However, such arguments are described later in the documentation in terms of a non-templated type. The non-templated type is the data type that the underlying function from the algorithmic engine is expecting and hence the type of data that the supplied data container must supply. For example, in quantiles, argument rv is described as having type RV in Section 2 in quantiles and being a double array in Section 5 in quantiles. A data container supplied as rv must hold the required data as a double, for example a std::vector<double> could be supplied.
The dimensions of array arguments are given in their description, for example a vector (a one-dimensional array) argument may be described as:
• a$\left(n\right)$ – double array
indicating that the vector should be of length $n$, or a matrix (a two-dimensional array) may be described as:
• a$\left(m,n\right)$ – double array
indicating that a $m×n$ matrix should be supplied (i.e., a matrix with $m$ rows and $n$ columns).
A number of functions in the NAG Library take a table as an argument. Here we define a table as containing $l$, $m×n$ matrices (i.e., a $m×n×l$ three-dimensional array), which may be described in the documentation as:
• a$\left(m,n,l\right)$ – double array
When declaring array arguments, you must ensure that all dimensions are of the documented size, i.e., you may not supply oversized array arguments.
For output array arguments, if a resize method, or equivalent, has been supplied then the argument does not need to be pre-allocated to the correct size. If such a method is not supplied then you must pre-allocate the argument prior to calling the function (see Section 3.2 for more details on the resize method).
When describing individual elements of arrays, the notation $\mathbf{a}\left(i\right)$, $\mathbf{a}\left(i,j\right)$ and $\mathbf{a}\left(i,j,k\right)$ is used for vectors, matrices and tables respectively, i.e., round brackets, $\left(\right)$. The indices used with this notation are zero based unless explicitly stated otherwise.
##### 2.1.3.1Callback Array Arguments
As with array arguments in the main wrapper, the interfaces supplied with the NAG CPP Interface support a number of data containers as arguments to callback functions. Unlike the array arguments in the main wrapper, when documenting callback functions, any arrays are described in terms of a particular array1D, array2D or array3D (see for example objfun). However, you can write your callback function using any of the supported data containers as described in Section 3.
If implementing your own custom data container for use with the callback function (see Section 3.3.2), the specialization of array1D, array2D or array3D documented is the class types your specialization of nagcpp::data_handling::convert_nag_array_to_user_t must handle.

#### 2.1.4Structure of the Error Messages

Any error or warning messages that a function may return are categorised by exception type (see for example Section 6 in contfn_​brent). By default errors raised by a function will be thrown as exceptions, warnings will not. Details of any warnings raised can be obtained via fail. See Section 5 for details on how to change this behaviour.
The notation $⟨\mathit{\text{value}}⟩$ appearing in the documented error message is a place holder that will be populated by the value of a variable, argument name or some other piece of information when that error message is displayed.

#### 2.1.5Example Programs and Results

Where available, the example program in the Example Section of the function document illustrates a simple call of the function. These example programs are distributed with the NAG CPP Interface in the example subdirectory and the expected results in the baseresults subdirectory.
For some example programs a number of alternative results files have been supplied, for example, ‘ex_e04mt.r’, ‘ex_e04mt.r_v1’, ‘ex_e04mt.r_v2’ are all results files obtained from running ‘ex_e04mt.cpp’ on different platforms. Only one of these results files (‘ex_e04mt.r’) will appear in the function documentation.
Note that even where variant results files have been supplied, the results you obtain may not agree exactly with any of the results files supplied, however any differences should be of a similar magnitude to that displayed between the variants.
Some examples use data container types that are only supported if that support is switched on (for example ‘ex_e04fg_boost.cpp’). See Section 3.1 for information on how to do this.

### 2.2Class Documentation

Documentation for several classes is provided. In many cases these classes contain members that are designed for use by the wrappers supplied by the NAG CPP Interface rather than directly. In such cases full documentation is only supplied for those members intended for direct use. Documentation for any other members will only be in the form of code comments.
Arguments to methods use the same classification of intent as described in Section 2.1.1 and may containt constraint information as described in Section 2.1.2.

### 2.3Communication Class Documentation

Many functions in the NAG CPP Interface need to communicate with each other, for example, in order to solve an optimization problem using handle_​solve_​ipopt you first need to set up the type of problem you wish to solve using one or more functions from Chapter E04. The mechanism used to communicate between functions is via a series of communication classes, for example, CommE04RA is used by handle_​solve_​ipopt, amongst others. Each class follows a similar format.
• Constructor: the main constructor has the same prototype as the initialization function, so for example in CommE04RA the main constructor has the same prototype as handle_​init.
• Destructor: as well as cleaning up any internally allocated memory, where appropriate, the destructor will call any associated deallocation functions from the NAG Library. For example, the destructor for CommE04RA calls handle_​free.
• Setter / Getter: many of the communication classes are used to pass around information on optional parameters used to control some aspect of the underlying algorithm (see Section 4 for more details). In such cases, where available, the class will contain a generic set and get methods. These have the same prototype as the equivalent function, for example, the communication information initialized by handle_​init has a getter function in the form of handle_​opt_​get and a setter function in the form of handle_​opt_​set. In CommE04RA the prototype of the nagcpp::opt::CommE04RA::get method is the same as handle_​opt_​get and the prototype of the nagcpp::opt::CommE04RA::set method is the same as handle_​opt_​set.
It should be noted that it will not usually be necessary to call the generic setter or getter methods as each optional parameter has its own setter and / or getter (where available).
• Setter for a specific optional parameter: where appropriate, each optional parameter has its own setter method. The name of the method is based on the documented name of the optional parameter (with all spaces removed), takes a single argument (the value to set the optional parameter to) and returns a reference to the communication class (hence allowing the calls to be chained). For example, handle_​solve_​lp_​ipm has the optional parameter LPIPM Monitor Frequency which controls the number of times the monitoring function is called. The setter method for LPIPM Monitor Frequency is LPIPMMonitorFrequency which takes a single int argument setting the frequency.
• Getter for a specific optional parameter: where appropriate, each optional parameter has its own getter method. The name of the method is similar to the setter method, just prepended by ‘get_’. For example, the name of the getter method for LPIPM Monitor Frequency is get_LPIPMMonitorFrequency. The getter methods take no arguments and return the value of the optional parameter.
Each communication class has its own documentation. These documents can be found by following the links in the documentation for the function you are interested in.
A number of example programs change optional parameters through the communication class, see for example Section 10 in handle_​solve_​lp_​ipm and Section 10 in handle_​solve_​ipopt.

### 2.4Implementation-dependent Information

In order to support all implementations of the NAG Library, the Manual has adopted a convention of using bold italics to distinguish terms which have different interpretations in different implementations.
One bold italicised term is machine precision, which denotes the relative precision to which real floating-point numbers are stored in the computer, e.g., in an implementation with approximately 16 decimal digits of precision, machine precision has a value of approximately ${10}^{-16}$.
The precise value of machine precision is given by the function precision.

## 3Data Containers

As noted above, the actual variable passed as an array argument to the function is referred to as a data container in this documentation. The wrappers supplied by the NAG CPP Interface support a number of data containers. The type of data containers supported are divided into two groups, those supported as arguments to the main function interface and those supported as arguments to callback functions.
A list of supported data containers is given in Section 3.1.
The wrappers supplied by the NAG CPP Interface can, in fact, support any arbitrary data container as long as that data container implements a number of standard methods (see Section 3.2).

### 3.1Supported Types

The following types are supported as arguments to both the main function interface and to callback functions:
• array1D
• array2D
• array3D
• std::vector<T>.
• boost::numeric::ublas::vector<T>, support for this type must be switched on by defining #HAVE_BOOST_VECTOR.
• boost::numeric::ublas::matrix<T>, support for this type must be switched on by defining #HAVE_BOOST_MATRIX.
where T is either double, int or string.
In a callback function it will usually be more efficient to use either array1D, array2D or array3D. These classes work directly with the arrays used by the algorithmic engine, whereas std::vector<T>, boost::numeric::ublas::vector<T> and boost::numeric::ublas::matrix<T> all require data to be copied in and out. Similarly, when used as an argument to the main function the following data containers require a full copy of the data to be made: boost::numeric::ublas::vector<T> and boost::numeric::ublas::matrix<T>.
The pre-processor variables like #HAVE_BOOST_VECTOR can either be defined via compiler flags when compiling, or by uncommenting the corresponding entry in ‘nagcpp_available_data_containers.hpp’ in the utility subdirectory.

### 3.2Using Arbitrary Data Containers

The NAG CPP Interface support the use of any arbitrary data container as an argument to the main function interface, as long as that data container implements a number of standard methods. The methods required for a data container to be used as a vector (1D array) are described in DummyVectorDataContainer, the methods required for it to be used as a matrix (2D array) are described in DummyMatrixDataContainer and the methods required for it to be used as a table (3D array) are described in DummyTableDataContainer.
When using an arbitrary data container, if data of the wrong type is supplied, i.e., the function documentation states that the array argument in question should supply data of type double, but the supplied data container is of type float, then the data is converted, using std::static_cast, and copied both into and out of the calls to the algorithmic engine.
Examples of data containers of each type are included in the include subdirectory, along with a generic data container that can be used as any of the three types (as a 1D, 2D or 3D array).
Arbitrary data containers can not be used as arguments to callback functions, only those data containers listed in Section 3 can be used.
See Section 3.3 for information on using data containers which do not implement the required standard methods and for information on using a custom data container as an argument in a callback function.

#### 3.2.1Storage Order

When designing a multi-dimensional data container for use with the NAG CPP Interface (i.e., anything other than a vector), the underlying storage used for the data must be considered. Ultimately the data container must deliver the data in a contiguous block of memory (for example, through the data method). The algorithmic engine supports data stored in one of two ways, column-major order or row-major order.
For $A$, an $m×n$ matrix, the value in the $i$th row and $j$th column must be stored in the $p$th element of the contiguous memory, with:
• $p=\left(i-1\right)×n+j-1$ when using row-major order and
• $p=\left(j-1\right)×m+i-1$ when using column-major order.
for $i=1,2,\dots m$ and $j=1,2,\dots n$.
For a table containing $l$, $m×n$ matrices (i.e., a $m×n×l$ three-dimensional array), the value in the $i$th row and $j$th column of the matrix in the $k$th table must be stored in the $p$th element of the contiguous memory, with:
• $p=\left(i-1\right)×n×l+\left(j-1\right)×m+k-1$ when using row-major order and
• $p=\left(k-1\right)×m×n+\left(j-1\right)×m+i-1$ when using column-major order.
for $i=1,2,\dots m$ and $j=1,2,\dots n$.
For performance reasons, it is usually preferable if the data is stored in column-major order.
If a function has multiple multi-dimensional array arguments then they must all use the same internal storage order, i.e., they must all be in column-major order or all in row-major order. Any multi-dimensional array in a callback function will have the storage order used when calling the main function. If the main function does not have any multi-dimensional array arguments then the default storage order is used as defined by default_to_col_major.

### 3.3Non-standard Data Containers

#### 3.3.1As Arguments to the Main Function

If you are unable or unwilling to implement the required standard methods in your data container then it can still be used as an argument to a function, however it will take a bit more work. In such a case a specialization of the nagcpp::data_handling::RawData class must be supplied. What this entails is not documented here, however examples can be found in the utility subdirectory in, for example, ‘nagcpp_data_handling_boost_matrix.hpp’ or ‘nagcpp_data_handling_boost_vector.hpp’.
Once you have implemented the specialization you can test that it performs as expected using one of the unit tests in the tests subdirectory, specifically ‘ut_data_handling_1D.cpp’, ‘ut_data_handling_2D.cpp’ or ‘ut_data_handling_3D.cpp’. Code comments in the relevant file gives details on how to incorporate your own data container into the unit test. An example of the additional utility functions that you must supply can be found in the include subdirectory in, for example ‘nagcpp_ut_boost_vector_setup.hpp’ and ‘nagcpp_ut_boost_vector_setup.hpp’.

#### 3.3.2As Arguments to a Callback Function

In order to use a non-supported data container as an argument in a callback function a specialization of the nagcpp::data_handling::convert_nag_array_to_user_t must be supplied. What this entails is not documented here, however examples can be found in the utility subdirectory in, for example, ‘nagcpp_data_handling_std_vector.hpp’, ‘nagcpp_data_handling_boost_matrix.hpp’ or ‘nagcpp_data_handling_boost_vector.hpp’.
Once the specialization has been implemented the same unit tests as described in Section 3.3.1 can be used to test its functionality, and the same examples apply.

## 4Optional Arguments

There are two types of optional arguments to functions in the NAG CPP Interface, those that are supplied through the communication class (Section 2.3) and those that are no different to standard interface arguments, other than the fact that a sensible default value can be chosen. For example in the function prob_​students_​t_​noncentral, sensible default values can be chosen for both tol and maxit. Rather than being supplied directly in the function interface, such arguments are supplied via an optional argument class, which is unique to each function. Each optional argument is described in the individual function documentation.
Each optional argument class is a child of Optional and as such can also be used for error handling and controlling file input/output.
Each optional argument has two methods associated with it, a getter and a setter. The name of the setter method is based on the documented name of the optional argument, takes a single argument (the value to set the optional argument to) and returns a reference to the optional argument class (hence allowing the calls to be chained). For example, lars has an optional argument pred which indicates the type of data pre-processing to perform. The name of the setter method for pred is nagcpp:g02::OptionalG02MA::pred and it takes a single int argument. The name of the getter method associated with an optional argument is similar to the setter method, just prepended by ‘get_’, so the getter for pred is nagcpp:g02::OptionalG02MA::get_pred. The getter methods take no arguments and return the value of the optional argument.
In some cases the default value for a particular argument is independent of the value of any other function argument, for example, tol in prob_​students_​t_​noncentral has a default values of . In these instances the default value can be queried as soon as the optional argument class is instantiated. In other cases the default value depends on one more input arguments, see for example maxit in lars whose default value depends on mtype. In these instances the default can only be queried after the associated function has been run.

## 5Error Handling

Error handling is done through the ErrorHandler class. The behaviour of ErrorHandler can be controlled at a global level through GLOBAL_ERROR_HANDLER_CONTROL or on a function by function basis through the instance of ErrorHandler stored in the optional argument class (see Section 4).
See Section 10 in lars for an example of using the optional argument class to check for warnings issued by a function.
Irrespective of whether the issuing of a warning causes an exception to be thrown or not, when a warning is issued all output (and input/output) arguments will be populated as documented. In the case of a non-void function, if the issuing of a warning causes an exception to be thrown, then the return value can be obtained via return_value.
Irrespective of whether the issuing of an error causes an exception to be thrown or not, when an error is issued the state of any output (and input/output) arguments are undefined, unless stated otherwise in the individual function documentation.

## 6File input/output

Within the NAG CPP Interface file input/output is done through the IOManager class which is used to translate between std::istream or std::ostream and the input/output unit numbers used in the algorithmic engine.