Structure of the Library

The NAG Library for .NET is a comprehensive collection of static methods for the solution of numerical and statistical problems. The library is essentially a derived product consisting of C# wrappers around the NAG Fortran Library.

We have specified NagLibrary as the library namespace. Each class of the NAG Library, is a devoted to a branch of numerical analysis or statistics. Each class has a three-character name and a title, e.g.,

Class D01 — Quadrature

Exceptionally, class S has one-character name. The classes and their names are based on the ACM modified SHARE classification index (see ACM (1960–1976)). All documented methods have five-character names which begin with the characters of the class name, for example

c06eb

The letters of the method name are always lower case, the second and third characters being digits.

Further details of the structure of the library and the naming scheme used may be found in the introduction to the NAG Fortran Library available from the NAG website.

By and large each Fortran routine has been wrapped, with a reduced parameter set, to form a static .NET method. In particular we have removed work arrays unless they contain useful information on return. We have also removed array dimension parameters that are not needed in the .NET environment due to the query facilities provided by .NET array types.

Data Types

The majority of parameters are either scalar or arrays of type Int32 and Double, or the Complex type described below. Exceptions to this, where methods have parameters of types defined within the library, are described in the next secton.

Complex

The Complex class is defined by:

public Complex(double r, double i)
{
 re = r;
 im = i;
}

Several methods are defined to allow convertion between complex values to and strings. The type inherits the IFormattable interface so Complex values may be formatted in Console.Write and similar methods. The format specified is applied separately to each of the real and imaginary parts. The Complex class also has several overloaded operators for the standard arithmetic operations.

DataReader

The DataReader is a small wrapper around the standard StreamReader class. It serves two functions.

  1. It provides methods for parsing streams containing ASCII data in the formats used in the NAG example programs. This feature may be of limited use in other contexts.
  2. A DataReader may be used to hold a stream consisting of several option setting strings, one per line. the option setting classes described below have an overloaded Set method, which if passed a DataReader stream will extract each option setting line and call the appropriate option Set method on the resulting string. See the example below setting options in an E05 example.

Communication Classes

There are some chapters of the NAG Library where we have not kept to strictly one to one mapping of Fortran routines to .NET methods. These are described below.

C05

In contrast to many methods in the NAG Library which require function parameters (delegates), some methods in this class obtain the information required by repeatedly returning to the calling program. In these cases information has to be stored in an intermediate communication class which can then be passed as a parameter to the appropriate C05 method. e.g.

C05.c05ndCommunications communications  = new C05.c05ndCommunications(n);
C05.c05nd(ref irevcm, n, x, fvec, xtol, ml, mu, epsfcn, mode, diag, factor, fjac, r, qtf,
          communications, out ifail );
C09

In the C09 class the methods follow a pattern in which there is an initialisation phase which collects information that is subsequently used by other class methods. Here the initialisation is carried out by the C09Communications class and the resultant object is passed as a parameter to the following method call.

C09.C09Communications c09comm = new C09.C09Communications(wavnam, wtrans, mode, n, out ifail);
C09.c09cc(n, x, c, dwtlev, c09comm, out ifail);
E04

In the E04 class, the optimization methods can be fine tuned by a large number of parameters which generally have default values. Consequently there is an initialisation phase associated with these methods. The initialisation is carried out by a method related options class. The Set method of the options class can then be used to provide set additional parameters. e.g.

E04.e04ucOptions options = new E04.e04ucOptions();
options.Set("List");
E04.e04uc(n, nclin, ncnln, a, bl, bu, confunE04UCA, objfunE04UCA, out iter, istate, c,
          cjac, clamda, out objf, objgrd, r, x, options, out ifail);
E05

In the E05 class, the option handling in E05 is very similar to that of E04. e.g.

sr = new DataReader("../exampledata/e05jbe.d");
E05.e05jbOptions options = new E05.e05jbOptions();
options.Set(sr);
options.Set("Local Searches Limit = 40");
E05.e05jb(n, objfunE05JB, ibound, iinit, bl, bu, list, numpts, initpt, monitE05JB, x, out obj,
           options, out ifail);

G05

In the G05 class, the random number generators have to be initialised to a repeatable or a non-repeatable state and this state information is then communicated to the generator methods. We have provided the G05State class to perform the initialisation; G05State constructs the object which is then passed as a parameter to the required G05 method. e.g.

G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
G05.g05ph(2, n, xmean, ip, phi,iq,theta, avar,r,  g05State, out var, x, out ifail);

Output from the Library.

The output from library can be categorized into two, error/warning messages and monitoring output mainly from the optimization and statistical methods. This output is directed to the console by default. However, the PrintManager class can be used to direct the output to a stream of the user's choice. The PrintManager class specifies two properties, Warning and Message to allow the user to define separate delegates, one for warning/errors and the other for monitoring.

For example, to switch off both the warnings and monitoring output you could use:

PrintManager.Message = new PrintManager.MessageLogger(discardmessage);
PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);

and define discardmessage as:

static void discardmessage(String message)
{
}

In addition to the static properties on the PrintManager class, which set the global default printing behaviour for the library, the options classes described above also have Warning and Method properties. By setting these properties on instances of an options class the printing behaviour of individual method calls may be controlled.

Error Handling

If a routine can signals an error due to incorrect data input or the underlying algorithm can return a failure, the method will have an ifail parameter. If this parameter has a value of zero on return then the method has succeded. A non-zero value almost always indicates failure, however sometimes the answers are acceptable, in particular many methods in E04 may return acceptable results despite a non zero ifail warning. The accompanying message should make it clear whether a non-zero return of ifail is acceptable. We have chosen to use return values of ifail rather than throw exceptions ourselves to allow you the opportunity to throw appropriate exceptions based on your application's requirements.

Example Programs

We have provided example programs to illustrate the use of the NAG numerical methods. These can be found in the installation folder (normally in \Program Files\NAG\NAG Library for .NET\ExampleClasses). These programs are for use in Console projects and they may be helpful templates for your own program.

We have provided a DataReader class primarily for use with our example data files.

Documentation

The documentation has been supplied as IntelliSense, integrated Visual Studio help files and standalone Windows HTML help file. It is generated from our Fortran Library documentation, polished where possible. The documentation has been transformed from our XML based Fortran Library documentation. Since the present library does not encompass the full functionality of the NAG Library there are references to class methods that are currently not present. If users need to use these methods then generally speaking they can be called from Fortran directly. See the NAG Fortran Library documentation. We would certainly like to hear from you if there are methods that are not currently available that you would like to see in the next release of this product. Please refer to the Fortran Library documentation in case of ambiguity in the NAG Library for .NET documentation.

Library Constants

Support from NAG

Post Release Information

Please check the following URL:

http://www.nag.co.uk/doc/inun/dt02/w3adal/postrelease.html

for details of any new information related to the applicability or usage of this implementation.

NAG Response Centres

The NAG Response Centres are available for general enquiries from all users and also for technical queries from sites that subscribe to the support service.

The Response Centres are open during office hours, but contact is possible by fax, email and telephone (answering machine) at all times. Please see the NAG web site for contact details.

When contacting one of the NAG Response Centres, it helps us to deal with your query quickly if you can quote your NAG user reference and NAG product code.

NAG Web Site

The NAG web site is an information service providing items of interest to users and prospective users of NAG products and services. The information is regularly updated and reviewed, and includes implementation availability, descriptions of products, downloadable software, case studies, industry articles and technical reports. The NAG web site can be accessed via: